Memory, search and daily maintenance

An agent’s memory is a collection of readable files, not one ever-growing prompt. Hilo coordinates the upkeep of those files and maintains a separate search index. The files remain authoritative if indexing is disabled or unavailable.

Nodes update themselves from the signed release channel, so everything on this page — the Hilo system contact, fleet digests, pending-input rebuild and the Saved with warnings outcome — is available on every current node. A node that has been switched off for a long time picks these up on its next update check after it comes back.

Where memories live

Under the node home, each agent has its own directory:

agents/<name>/
  CLAUDE.md                    identity and agent-specific instructions
  memory/
    MEMORY.md                  small contents page and essential orientation
    projects/INDEX.md          optional category index
    projects/example.md        detailed, durable knowledge
    daily/                     dated notes, when useful
  runtime/hilo-memory.sqlite3   derived semantic-search database

These category names are examples, not a mandatory taxonomy. An existing root MEMORY.md and legacy note names remain supported. Hilo does not rename or rewrite all imported memories on upgrade. Per-conversation handovers and maintenance checkpoints are stored in the node’s organization database.

Keep the startup index selective: a few essential facts and links to useful categories, not one row for every fact or file forever. Detailed notes are read when relevant. Hilo targets 160 lines / 20,000 UTF-8 bytes for the index and warns above 200 lines / 24,000 bytes. Exceeding those recommendations does not truncate saved notes or fail consolidation. These are Hilo’s policy budgets, not a promise about every Claude Code version’s loading behavior. A growing category can split into smaller ones without making the startup index grow with it.

What nightly consolidation does

Hilo tracks new retained transcript material since the last completed checkpoint. It supplies bounded batches to an agent turn using that agent’s configured Claude connection. The agent reads relevant existing notes, updates durable facts, records decisions and unfinished work, and supplies conversation handovers and a completion receipt. It should update an existing subject before creating another duplicate note.

The node verifies the receipt and saved files. Missing required notes or handovers, unsafe file paths, mismatched batch identity and credential material still stop completion. Oversized indexes, broken contents links and duplicate receipt paths produce Saved with warnings when the essential checks pass; they do not block indexing or session renewal. Hilo does not rewrite the notes to satisfy a size target or validate whether every remembered fact is correct.

Conversation handovers target 8,000 characters. Longer useful handovers are preserved with a warning up to a 64,000-character technical ceiling; put further detail in memory files and link to it from the handover.

Coverage advances only after the whole run succeeds. A failed batch does not silently skip to the next one. The batch budget limits model work; a remaining backlog stays pending for another run. Consolidation consumes your agent model allowance, unlike the Hilo-funded embedding service.

Universal instructions for memory storage, consolidation and search are injected by Hilo’s workspace rules and tool descriptions. You do not need to copy them into every agent’s CLAUDE.md. That file should hold identity, responsibilities and genuinely agent-specific preferences. Existing useful memories are reused, not rewritten wholesale.

Passwords, tokens and private keys do not belong in memory. Hilo corrects an overly broad check so ordinary service emails, account identifiers and plain endpoints are not treated as secrets merely because they arrived alongside credentials.

Search and vector indexing

Agents use the workspace_memory_search tool to search their own saved memories and follow returned paths and line ranges to the source. Search is on demand; Hilo does not automatically paste the entire memory library into every turn. The tool can scope searches to knowledge, history, or all (the default). Those scopes use file locations, not a guarantee that a fact is current; check dates and sources.

When semantic memory is enabled, Hilo generates embeddings for changed saved passages and stores the vectors and passages in the agent’s local SQLite database. Unchanged vectors are reused. The supervised indexer runs separately from Claude turns, waits for incomplete consolidation, and refreshes after consolidation succeeds. It replaces the old model-driven indexing cron; it does not import an old LanceDB database.

A replacement snapshot is published only when it is ready. If a refresh fails, the previous snapshot remains. When semantic search is disabled or unavailable, the tool falls back to keyword search over readable local memory files. An indexing problem does not erase notes or prevent otherwise-verified session renewal.

Hilo pays for the embedding service, subject to shared service and request limits; there is no organization monthly or per-seat byte quota. You do not supply an embedding API key for this service. Saved memory text and search queries transit Hilo to OpenAI; raw transcripts and tool outputs are not index inputs. See the privacy disclosure before enabling it.

Settings and fresh sessions

Open Admin → Agents → the agent → Overview. Set its consolidation schedule, timezone, batch limit, renewal option and semantic-memory enrollment there. Each agent has concrete settings. Bulk settings changes only the agents and fields explicitly selected; it does not establish defaults inherited by future agents.

Hilo asks for confirmation before Consolidate now / retry and Index now / retry queue immediate work. Consolidation uses the agent’s Claude allowance or API billing; indexing uses Hilo’s funded embedding allowance. Cancelling queues nothing. Manual consolidation uses the saved settings and starts a fresh batch budget, not any unsaved form edits.

If renewal is enabled, a successful consolidation queues a new session generation. Each conversation starts fresh on its next turn, with the saved handover and memory guidance available. Hilo does not interrupt today’s running session, and a failed or unfinished consolidation does not renew it. Finishing one batch is not finishing the run.

Fleet reports

Administrators get a private Hilo contact with a daily fleet summary, by default at 07:00 in their profile timezone, plus deduplicated failure alerts. Its Report settings controls timing and alerts. It is system software, not an agent or a paid agent seat: it has no model and cannot execute requests.

The report distinguishes verified batch progress, Saved with warnings, failed/paused work, index freshness and session renewal queued for upcoming turns. Schedule state is reported separately: a paused schedule does not undo completed work. Warnings appear in the summary without triggering failure alerts. Stale or missing remote-computer status is shown as unavailable, not successful. Use each agent’s link for follow-up work. Routine batch output stays in internal maintenance conversations, not every agent DM. A completely stopped main node cannot send its own report; retain ordinary machine monitoring.

Adopting an existing memory setup

Keep the notes you already have. Review whether the startup index needs a smaller contents-page structure, enable the desired Hilo settings, and retire overlapping custom consolidation/indexing jobs after checking for unrelated duties in them. Hilo cannot safely discover or disable every script an operator installed outside it. Historical chat archives can stay reference-only when their useful information is already in the saved notes; no blanket replay is required by the new policy.

For a scheduled job with a huge growing journal inside SKILL.md, keep stable rules in that file and write dated execution rounds to a separate journal. Preserve business rules and include new findings in normal job completion messages. Hilo recognizes the exact legacy launchd instruction wrapper and substitutes a short document reference in consolidation input; it keeps subsequent findings and original transcripts intact. Unknown wrappers remain unchanged.

An already frozen oversized run is not silently replaced on update. Use Rebuild pending input for failed/paused work on the agent’s owning computer. It starts from the last completed checkpoint, preserves notes and old snapshots, and resets the configured batch budget. Partially processed pending material may be revisited. This is an explicit recovery action, not an automatic migration or permission to reprocess six months of already-consolidated history.

Next: Agents · Backups and recovery

LAST UPDATED 2026-09-14