Memória profunda: o MemoryStore de snapshot congelado

Um agente sem memória recomeça do zero a cada conversa. Dar memória a ele parece simples — "é só escrever num arquivo". O difícil é dar memória sem quebrar o cache do modelo e sem mentir sobre o que foi salvo. O MemoryStore resolve os dois com um único truque e uma única assimetria.

O subsistema todo é uma classe e algumas constantes, todas exportações nomeadas de packages/hermes/src/index.ts:

A operação em si é uma união discriminada em tempo de compilação — não existe um saco de "params" tipado por string:

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

Só os dois valores que cruzam uma fronteira sem tipo na fonte Python — target e action — são validados por Zod em tempo de execução (memory/schema.ts: z.enum(['memory','user']) e z.enum(['add','replace','remove'])). O payload da operação é uma união em tempo de compilação, então uma forma ilegal nem chega a ser escrita.

O store guarda duas realidades paralelas. O load() lê o disco, deduplica e congela um snapshot; o apply() muta as entradas vivas e as persiste — mas nunca toca no snapshot.

O snapshot congelado fica imóvel no prompt durante toda a sessão; as escritas vão ao disco na hora. Eles só se reconciliam no próximo load().

// packages/hermes/src/memory/memory-store.ts (load + renderSnapshot, condensado)
async load(): Promise<Result<void, Error>> {
  // … lê MEMORY.md + USER.md via FsPort …
  this.memoryEntries = dedupe(memory.value);   // paridade com dict.fromkeys do Python
  this.userEntries   = dedupe(user.value);
  this.snapshot = {                            // congelado UMA vez, aqui
    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];   // estado do load, não o vivo
  return block.length > 0 ? block : undefined;
}

replace e remove não recebem um índice nem um id. Eles recebem um trecho curto e o store acha a única entrada que o contém. O matcher falha fechado na ambiguidade:

A regra de localização por substring: opera com um casamento, falha fechado em casamentos distintos, e trata duplicatas idênticas como seguras.

// packages/hermes/src/memory/memory-store.ts — 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.`));
  }
  // Todas idênticas — seguro operar na primeira.
}

A sutileza: vários casamentos só são erro quando são entradas distintas. Se todos os casamentos são exatamente o mesmo texto (duplicatas verdadeiras), agir na primeira é seguro — a regra de fidelidade da fonte. Duplicatas não conseguem entrar via add() (ele deduplica), então o teste as semeia no disco e carrega para exercitar esse ramo.

Os limites são contados em caracteres, não tokens, porque a contagem de caracteres é independente do modelo. E o crucial: o ENTRY_DELIMITER conta contra o orçamento — o store mede o comprimento já unido, exatamente o que vai para o disco:

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

O teste "counts the delimiter against the budget" fixa isso: 'aaa' + '\n§\n' (3 caracteres) + 'bbb' = 9 caracteres, então um limite de 9 passa e 8 falha. Quando um add estouraria, o erro não é uma falha seca — ele diz ao agente para consolidar ("use 'replace' to merge … or 'remove' stale entries, then retry"), transformando um teto rígido num convite à curadoria.

// packages/hermes/src/memory/memory-store.ts — leitura tolerante
if (!exists.value) return ok([]);       // arquivo ausente → store vazio, nunca quebra
// … lê e divide em entradas …
return ok(splitEntries(read.value));

Cinco ideias para levar — passe pelos slides e teste se você consegue reproduzir cada uma de memória antes de seguir.