Memory and knowledge

How the agents remember, and where each kind of knowledge lives. Read this before writing any agent, because the single most common way an agent system fails in front of a customer is forgetting something it was already told.

---

The constraint that shapes everything

Hermes' memory is 2,200 characters.

~/.hermes/memories/MEMORY.md is a flat file of §-separated entries, capped by memory.memory_char_limit: 2200 (plus USER.md at 1375), flushed every ~6 turns. That is roughly four to six facts.

It will evict, and it evicts silently. So:

Nothing the system depends on may live in Hermes memory. It is a hot scratchpad for the current task, never a source of truth. Everything durable lives in Postgres, a git repo, or the Operator KB, and is retrieved rather than remembered.

An agent that relies on Hermes memory to know what it promised a client will, eventually and unpredictably, forget.

---

Six stores, six jobs

1 · Hot context — Hermes memory

Use for: the job currently in flight, the client currently being answered. Nothing else. Never put a promise, a price, a deadline or a client fact here. Write those to store 3 or 4 and read them back.

2 · Client truth — the dossier

Already specified in agents/02-dossier.md. One file, cited, in the client's own repo. Every factual claim any agent makes must trace to it. Diffable, so a change to a client's hours is visible in history.

3 · Job state — Postgres

jobs (stage, gate_level, amounts, timestamps) and runs (per-stage attempts, duration, spend). Already built. This answers "where is it and what has it cost", never "what did we say to them".

4 · The conversation — this did not exist and it is the biggest gap

Nothing in the design stored what was said to a client. The Account Manager records revisions "verbatim" — but to where? An agent that re-asks a question the client already answered, or re-offers something they already declined, reads as a machine and undoes the whole point of the voice work.

client_messages
  id, job_id, business_id,
  direction     -- in | out
  channel       -- email | sms
  body          -- verbatim, never summarised
  sentiment     -- for the unhappiness trigger
  agent         -- which agent sent it
  in_reply_to
  sent_at

Rules:

• Every agent reads the thread before writing to a client. No exceptions.
• Bodies are stored verbatim. A paraphrased complaint destroys the diagnostic value that agents/08 calls the most valuable dataset in the system.
• Customer Success reads the entire history before any month-3 offer. Pitching content to someone who complained about the blog in week two is worse than not pitching at all.
• The unhappiness trigger runs on insert of an inbound message, so escalation is immediate rather than waiting for a poll.

5 · Institutional learning — Operator KB

Do not build a second knowledge base. projects/operator-kb/ already provides exactly what this needs: hybrid retrieval (full-text + vector + IDF + age decay, RRF-fused, LLM reranked) over pgvector, and — the part that matters — contradiction-aware push-back.

kb_challenge is the reason to use this rather than a vector store: it is the inverse of search, it surfaces the demoted graveyard and correction reasons, and it is calibrated to stay silent when a plan matches current practice. Applied here, it stops the copy agent cheerfully repeating an angle that has already failed twice.

A new connector (connectors/site-factory.mjs, alongside brain/granola/github) feeds it:

• client rejection reasons, verbatim, tagged by cause (facts / voice / missed something)
• QA escapes and the check that now catches them
• approved pages, by trade, as worked examples
• complaint wording
• which research angles survived into copy, and which never did

Every agent calls kb_challenge before a consequential decision — an angle, a voice choice, an upsell — and kb_confirm/kb_correct after the outcome is known. That closing of the loop is what makes the system compound instead of repeating itself.

6 · Doctrine — these documents

The nine agent specs, website-build.mjs (the commercial terms), and the AiSearch voice guide. Humans read them in git; agents retrieve them through the KB. website-build.mjs stays the only source of prices — an agent quoting a price from the KB instead of the file is a bug, because the file is what the agreement renders from.

---

What each agent reads and writes

---

Hygiene

• Verbatim or nothing. Client words are stored as said. Summaries are derived, never stored in place of the original.
• Retrieval over recall. An agent that "remembers" a price is a bug; it should read it.
• Corrections supersede, never delete. kb_correct keeps the graveyard, and the graveyard is what makes kb_challenge work.
• PII stays in Postgres and the client repo, not the KB. The KB learns patterns — "cafes reject stock photography" — not "Sam Whitcombe's phone number".
• The dossier is the only place a client fact may be asserted from. The KB holds craft knowledge, not client facts, and the two must never be confused.