O MemoryStore de snapshot congelado

Uma memória limitada, persistida em arquivo, que o agente carrega entre sessões — dois stores (MEMORY.md para as notas do próprio agente, USER.md para o que ele sabe sobre você), editados por uma única operação memory que localiza entradas por uma substring única e curta. Seu truque definidor é o snapshot congelado: o que o system prompt vê é capturado uma vez no load() e nunca se move, mesmo quando escritas no meio da sessão vão para o disco. É um CLONE fiel do tools/memory_tool.py do Hermes (1089 LOC).

01 · A intuição: o caderno congelado

Antes do código, a imagem. Pense num agente que tem um caderno com tudo o que precisa lembrar sobre você. No começo da conversa ele tira uma foto da página e cola essa foto no início da cabeça dele (o system prompt). Durante a conversa, ele pode rabiscar coisas novas no caderno — e esses rabiscos vão pro papel na hora. Mas a foto colada na cabeça não muda: continua mostrando o caderno como estava quando a sessão começou. Só na próxima conversa ele tira uma foto nova.

Essa é a tensão inteira da lição: a foto (snapshot) precisa ficar parada para o modelo não recalcular o prompt toda hora — mas os rabiscos (disco) precisam ser duráveis na hora, senão você perde a nota. O MemoryStore mantém as duas verdades ao mesmo tempo, de propósito.

02 · A API pública

O subsistema inteiro é uma classe e algumas constantes, todos exports nomeados em packages/hermes/src/index.ts:

Dois stores, dois propósitos

São dois arquivos com papéis diferentes — e tetos diferentes. O target de toda operação escolhe entre eles:

O tipo central, em duas linguagens

A operação em si é uma união discriminada em tempo de compilação — não há um saco de "params" tipado por string. Alterne entre a explicação simples e o tipo real:

// 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 };

Só os dois valores que cruzam uma fronteira não tipada na fonte Python — target e action — são validados em runtime com Zod (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 pode ser escrita.

O que volta de um apply() bem-sucedido

Toda mutação que dá certo devolve um MemoryOpOutcome — não um booleano, mas um relatório que diz ao agente o estado pós-escrita (quantas entradas, quantos chars usados, qual o teto):

03 · O invariante definidor: snapshot vs. estado vivo

O store mantém duas realidades paralelas. load() lê o disco, deduplica e congela um snapshot; apply() muta as entradas vivas e as persiste — mas nunca toca no snapshot. Esta linha do tempo é o coração da lição:

O código que congela

load() é o único lugar que escreve this.snapshot. renderSnapshot() só lê desse campo congelado — nunca do estado vivo:

// packages/hermes/src/memory/memory-store.ts:119-147 (condensado)
async load(): Promise<Result<void, Error>> {
  // … ler 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;
}

No load, a deduplicação preserva a ordem

Repare na linha dedupe(memory.value): ao ler do disco, entradas repetidas são colapsadas, mas a primeira ocorrência mantém sua posição — paridade exata com o dict.fromkeys do Python:

O formato do bloco que entra no prompt

O que renderBlock produz não é a lista crua — é um bloco com cabeçalho, separador e um indicador de uso embutido ([NN% — usados/teto chars]). Assim o próprio agente, ao ler seu system prompt, já vê quão cheio está o store e pode se auto-curar antes de estourar:

O custo de NÃO congelar — lado a lado

Para sentir por que isso importa, compare os dois mundos. À esquerda, um store ingênuo que injeta o estado vivo no prompt; à direita, o MemoryStore real:

Onde as duas verdades voltam a coincidir

A defasagem entre snapshot e disco não é permanente — ela dura exatamente uma sessão. Veja duas sessões em sequência: o que foi escrito na sessão 1 só aparece no snapshot da sessão 2, porque é o load() dela que tira a foto nova:

04 · As três operações: add / replace / remove (fluxograma)

Uma única apply() recebe a MemoryOp e decide o caminho pela action. Cada caminho tem sua própria checagem de fail-closed. Siga as setas — cada losango é uma pergunta que escolhe a rota:

05 · Localizar por substring única — sem IDs

replace e remove não recebem índice nem id. Recebem uma substring curta e o store acha a única entrada que a contém. O matcher falha fechado em ambiguidade:

// 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.`));
  }
  // Todas idênticas — seguro operar na primeira.
}

A sutileza: múltiplos matches só são erro quando são entradas distintas. Se todos os matches são exatamente o mesmo texto (duplicatas verdadeiras), agir na primeira é seguro — a regra de fidelidade da fonte. Duplicatas não entram via add() (ele deduplica), então o teste as semeia no disco e dá load para exercer esse ramo.

Os três desfechos do matcher

Toda chamada a locateUnique cai em um de três casos. Repare que distinto e duplicata têm a mesma contagem de matches (>1) mas desfechos opostos:

06 · O orçamento de chars — e por que o delimitador conta (worked)

Os limites são contados em caracteres, não tokens, porque contagens de chars são independentes de modelo. Crucialmente, o ENTRY_DELIMITER conta no orçamento — o store mede o comprimento juntado, exatamente o que vai para o disco:

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

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.

Sinta o orçamento — calculadora

Arraste os dois sliders. A barra cresce e troca de cor — verde = cabe, vermelho = estoura o teto. Repare que o total sempre inclui os delimitadores:

07 · A assimetria leitura/escrita — uma postura de design

A última peça é uma decisão sutil que reaparece pelo código todo: leitura e escrita falham de jeitos opostos, de propósito.

O round-trip de um § solto

O delimitador é a sequência completa '\n§\n' — não um § qualquer. splitEntries separa só nessa sequência, então uma entrada que contém um § no meio do texto sobrevive inteira ao salvar-e-recarregar:

Confusões comuns

08 · Como isso se encaixa

O MemoryStore não é uma peça solta — é o que dá continuidade entre sessões ao loop fechado da metodologia. Toda execução do agente começa lendo a memória persistida e termina (opcionalmente) escrevendo de volta o que aprendeu. Sem este store, cada sessão recomeçaria do zero. Veja onde a peça vive no fluxo real, e como o loop a lê no início e a escreve no fim:

Onde você está na metodologia. O Alembic é uma máquina que se constrói rodando o loop learn → analyze → execute → verify → improve. O MemoryStore é o que torna esse loop cumulativo: cada passagem pode deixar uma nota durável que a próxima encontra já no system prompt — sem re-explicar tudo, sem quebrar o cache de prefixo. É a diferença entre um agente que esquece tudo a cada turno e um que acumula contexto sobre você e sobre a tarefa. Para ver o quadro inteiro em movimento — como cada peça se liga às outras — abra o mapa interativo da metodologia.

09 · Na prática

Chega de teoria — toque o subsistema. Há dois caminhos reais, e vale distinguir um do outro com honestidade. O primeiro exercita exatamente o MemoryStore desta lição (o de MEMORY.md/USER.md, snapshot congelado) rodando os 23 testes do pacote. O segundo é o comando de CLI que você usa no dia a dia para a memória persistente do @alembic/hermes:

# 1) exercita ESTE store (o de snapshot congelado): roda os 23 casos de memory-store.test.ts
pnpm --filter @alembic/hermes test
# … vitest roda a suíte do pacote …
#  ✓ src/memory/memory-store.test.ts  (23 tests)
#  Test Files  N passed
#       Tests  N passed   ← inclui "snapshot reflects load-time disk state, not mid-session writes"

[uncertain] os números de arquivos/testes acima são ilustrativos do formato do vitest; o total varia com o estado do repositório. O invariante real é a suíte do @alembic/hermes verde — incluindo o caso que prova snapshot ≠ estado vivo (seção 03).

O segundo caminho é o comando de CLI alembic memory. Atenção a uma distinção importante: ele opera os multi-stores append-only do @alembic/hermes (episodic · semantic · procedural · decision · transcript) — a memória persistente que o harness usa. É a peça-irmã do MemoryStore desta lição (mesma casa, packages/hermes), não o store de MEMORY.md/USER.md em si. Ele é o jeito real de gravar e consultar memória pela linha de comando — offline e hermético:

# grava uma nota na memória semântica (offline, append-only JSONL)
alembic memory semantic add --record '{"text":"o usuário prefere PT-BR nas respostas"}'
# memory semantic: appended <id> (agent cli)
#   ~/.alembic/memory/semantic.jsonl

# consulta o que está gravado (mais recente primeiro)
alembic memory semantic list
# memory semantic: 1 record(s) under ~/.alembic/memory/semantic.jsonl
#   <id> [agent cli] at <timestamp>

O add exige --record <json> (um objeto JSON); sem ele o comando falha fechado com "memory add requires --record <json>". O --agent é opcional: no add ele recai para cli (um registro precisa de dono); no list, quando dado, filtra por aquele agente. O store fica em ~/.alembic/memory/<substore>.jsonl por padrão, ou onde --dir <path> apontar.

Fixe os conceitos (flashcards)

Clique pra virar. Tente lembrar a resposta antes de virar — recuperação ativa fixa mais que reler.