The frozen-snapshot MemoryStore

A bounded, file-backed memory the agent carries across sessions — two stores (MEMORY.md for the agent's own notes, USER.md for what it knows about you), edited by a single memory operation that locates entries by a short unique substring. Its defining trick is the frozen snapshot: what the system prompt sees is captured once at load and never moves, even as mid-session writes hit disk. This is a faithful CLONE of Hermes' tools/memory_tool.py (1089 LOC).

The public API

The whole subsystem is one class and a few constants, all named exports from packages/hermes/src/index.ts:

The operation itself is a compile-time discriminated union — there is no string-typed "params" bag:

// packages/hermes/src/memory/memory-store.ts:85-88
export type MemoryOp =
  | { readonly action: 'add'; readonly content: string }
  | { readonly action: 'replace'; readonly oldText: string; readonly content: string }
  | { readonly action: 'remove'; readonly oldText: string };

Only the two values that cross an untyped boundary in the Python source — target and action — are Zod-validated at runtime (memory/schema.ts: z.enum(['memory','user']) and z.enum(['add','replace','remove'])). The op payload is a compile-time union, so an illegal shape can't even be written.

The defining invariant: snapshot vs live state

The store holds two parallel realities. load() reads disk, dedupes, and freezes a snapshot; apply() mutates live entries and persists them — but never touches the snapshot:

// packages/hermes/src/memory/memory-store.ts:119-147 (condensed)
async load(): Promise<Result<void, Error>> {
  // … read MEMORY.md + USER.md via FsPort …
  this.memoryEntries = dedupe(memory.value);   // Python dict.fromkeys parity
  this.userEntries   = dedupe(user.value);
  this.snapshot = {                            // frozen ONCE, here
    memory: this.renderBlock('memory', this.memoryEntries),
    user:   this.renderBlock('user',   this.userEntries),
  };
  return ok(undefined);
}
renderSnapshot(target: MemoryTarget): string | undefined {
  const block = this.snapshot[target];   // load-time state, not live
  return block.length > 0 ? block : undefined;
}

Locate by unique substring — no IDs

replace and remove don't take an index or an id. They take a short substring and the store finds the one entry that contains it. The matcher fails closed on ambiguity:

// packages/hermes/src/memory/memory-store.ts:369-392 — locateUnique
const matches = entries.flatMap((entry, index) =>
  entry.includes(needle) ? [{ index, entry }] : [],
);
if (matches.length === 0) return err(new Error(`No entry matched '${needle}'.`));
if (matches.length > 1) {
  const distinct = new Set(matches.map((m) => m.entry));
  if (distinct.size > 1) {
    return err(new Error(`Multiple entries matched '${needle}'. Be more specific.`));
  }
  // All identical — safe to operate on the first.
}

The subtlety: multiple matches are only an error when they are distinct entries. If every match is the exact same text (true duplicates), acting on the first is safe — the source's fidelity rule. Duplicates can't arrive via add() (it dedupes), so the test seeds them on disk and loads to exercise that branch.

The char budget — and a deliberate asymmetry

Limits are counted in characters, not tokens, because char counts are model-independent. Crucially, the ENTRY_DELIMITER counts against the budget — the store measures the joined length, exactly what lands on disk:

// packages/hermes/src/memory/memory-store.ts:344-346
const joinedLength = (entries: readonly string[]): number =>
  entries.length === 0 ? 0 : entries.join(ENTRY_DELIMITER).length;

The test "counts the delimiter against the budget" pins it: 'aaa' + '\n§\n' (3 chars) + 'bbb' = 9 chars, so a limit of 9 passes and 8 fails. When an add would overflow, the error isn't a bare failure — it tells the agent to consolidate ("use 'replace' to merge … or 'remove' stale entries, then retry"), turning a hard cap into a curation prompt.

Common confusions