Concept
How the harness works with memory
The agent does two things with memory: it reads pages on demand when it needs context, and retains memories as the chat happens. Pages are rewritten from those memories in the background by Hindsight — the agent never has to.
Architecture
The agent only crosses the boundary into Hindsight to read pages and retain memories. Everything else — consolidating memories into facts, regenerating pages — happens server-side.
A normal conversation. The harness (Claude Code, Hermes, OpenClaw, NemoClaw…) is the runtime where the agent runs.
Two operations only — read knowledge pages, retain memories. Wired through MCP, a plugin, or a baked skill depending on the harness.
Memories get consolidated into facts; the refresh engine rewrites the agent's pages from those facts. The dashed arrows in the diagram are this loop.
Two primitives
Memories
Atomic, typed facts retained from conversations or ingested documents. Append-only — they preserve the full history of what the agent has seen.
Knowledge pages
Long-form markdown documents the agent fetches on demand when it needs context. Mutable — Hindsight rewrites them in the background as new memories arrive.
What the agent can call
The capabilities below are common to every harness, but the exact tool names, signatures, and what's actually wired up depend on the harness. The names shown are the Claude Code MCP tools (the most complete surface today); other harnesses expose the same families with different names — and may not implement every one. See the harness pages for the canonical list per integration.
Read
Pull context into the conversation.
list_pages— page ids and names in this bankget_page— read the full content of a pagerecall— semantic search across retained memories
Define page recipes
The agent sets what a page tracks — never its body.
create_page(id, name, source_query) — declare a new page; Hindsight populates the body.update_page(id, name?, source_query?) — change what a page tracks. Body stays managed by Hindsight.delete_page— remove a page
Bring in new content
Beyond what's already in the chat.
ingest(title, content) — add raw text as a memory.ingest_file(file_path) — read a local file and ingest it server-side.- Combined with the harness's web-fetch tool, the agent can also pull in arbitrary URLs the user points at.
Why this split exists
Two design choices worth justifying: storing memories and pages separately, and having Hindsight regenerate pages instead of letting the agent edit them mid-conversation.
Why memories and pages
- Different jobs. Memories preserve history; pages compress the current best understanding. A single layer would either overwrite history on every update or grow unbounded.
- Different access patterns. Pages are fetched whole when the agent decides it needs them — they have to fit a prompt at that moment. Memories are searched on demand and don't.
- Conflict stays auditable. When two memories disagree, the page resolves to the latest understanding while both memories stay on record. Tracing why a page says X means looking at the facts it recalled — not commit history of edits.
Why Hindsight refreshes pages, not the agent
- One conversation is the wrong input. A good page summarizes across sessions. The agent inside any single chat doesn't have that view.
- Contradictions resolve themselves. When two memories disagree, consolidation folds them into observations and the next refresh rewrites the page using the latest understanding — no agent has to pick a winner mid-conversation.
- Full audit trail. Hindsight retains every memory, every observation, and every page revision, and is optimised for that storage. Tracing why a page changed — which memory triggered it, which observation it came from — is built in. Agent-driven page edits would erase that lineage.
- Drift compounds. If an agent confabulates and writes the result to a page, the next session loads it as fact. Server-side refresh grounds every regeneration in retained memories, breaking the feedback loop.
- Concurrency. Two parallel sessions can both retain memories without coordination. They cannot both edit the same page without conflicts. Centralizing writes through Hindsight removes the problem.
- Latency. Consolidation runs async. In-loop page edits would block the user while the agent re-reads its own memory, dedupes, and rewrites.