How it fits together

Terminus is one binary with no daemon. Claude Code starts it when something happens, and it exits when that’s done.

Claude Code writes each session to a transcript and runs terminus hook on four events: SessionStart, UserPromptSubmit, SessionEnd and PostCompact. Each run starts a detached terminus ingest and then, on the first two events, may hand text back. The ingest copies each transcript’s new bytes into the store, indexes them and exits. One pass runs at a time, and a pass that finds another one running exits having done nothing.

Claude Code also starts terminus mcp and calls its three recall tools over stdio. The server opens no port, takes no lock and opens the store read-only for each call. The terminal commands read the same store.

The archived session is the record. Everything else in the store, the turns, the search index and the structured matches, comes from those blocks and can be rebuilt from them, except for an evicted session, whose blocks are gone.

The numbers that keep it out of your way

• A hook has 50 ms for its text. Past that, it hands over nothing for that event.
• A hook reads at most 1 MiB of stdin and waits at most 500 ms for it.
• Once a hook knows its event, it exits 0 whatever goes wrong, so it can’t block a prompt.
• Anything that goes wrong in a hook is one line on stderr. Failures in a pass are recorded for terminus status, since there’s no log file.
• A format change to the derived tables rebuilds them at the start of the next pass. An archive in another format is refused, never converted.

The design docs

Each part has a design doc that says how it works now, for an engineer who wants to see inside it. They live on GitHub, where the Mermaid diagrams render with nothing else installed. Start with the overview, which opens on one diagram of the whole system.