Thalamus

Memory for coding agents that can show where each thing it remembers came from.

When a Claude Code, Cursor or codex session ends, Thalamus reads the transcript and writes what happened into a graph database: the decisions and the reasons for them, the problems and how they were fixed, and the work left unfinished. The next session starts with the unfinished work in front of it and can search the rest.

Every stored item points back to the session or document it came from, and that transcript or document is kept unedited outside the graph. Each item also records whose word it rests on: yours, the agent's own reasoning, or a document the agent read. That record is what lets you ask the agent why it believes something and get an answer you can check.

What it does not show yet is that recalled memory makes an agent finish tasks better. It shows that memory gets surfaced; the status section says what would settle the rest.

The name is from the brain: the thalamus relays nearly every signal bound for a specialized region of the cortex, and gates what gets through.

session ends → transcript read → decisions, fixes and open work written to the graph
                                              ↓
                  next session starts with the open work and can search the rest

How it works

The project has its own vocabulary, and every term below is defined in Concepts. This section uses as little of it as it can.

Memory writes itself when a session ends

You don't curate it. A hook reads the retained transcript and extracts claims (a decision, a problem, a fix) and open threads (work the session did not finish). The next session opens already knowing where you left off.

Where an item came from decides how far it is trusted

Every item carries a trust tier: 0 for what you wrote down yourself, 1 for what an agent observed or worked out in its own sessions, 2 for outside documents from sources you approved, and 3 for outside content from anywhere else.

The data model defines an item's effective trust as the lowest tier anywhere in what it was derived from, so an agent's summary of a paper is trusted like the paper. No code computes that rule across a whole chain of derivations yet.

What is enforced today is narrower. When a session fetched pages with the agent's web tools, the claims that rest on those pages are stored at outside-document trust. The extractor marks them, and a mechanical check also catches a claim that repeats the page's wording when the mark is missing. A page fetched through the shell, and a claim that restates a page in different words, are not caught.

Recalled items come back quoted, with their source and tier attached: they inform the agent and never instruct it.

Each specialist keeps its own memory

Knowledge is split by domain. Each specialist, called an expert (a literature reviewer, a quality engineer, an architect), has its own graph of curated documents plus its own session history, and the pair is called a scope. A session runs as exactly one scope, fixed when the session starts. Asking another expert is a recorded consultation, never a search that happens to reach across.

A bad write is refused, not filtered later

One set of rules, the federation contract, is at once the data schema, the permission system and the trust boundary. A write that breaks it is rejected when it is written, rather than filtered out when it is read.

You can see what memory cost

Every memory lookup is logged and priced. thalamus pulse serves a live dashboard of what retrieval actually cost.

Quick start

Your graph starts empty and stays yours. Thalamus ships no seed graph, no export and no fixture corpus: a graph is one operator's session history, so every install is fresh, for everyone.

Prerequisites

The console additionally needs tmux: it runs pinned sessions as tmux windows (docs/console.md).

Install

git clone https://github.com/Ybx-jp/thalamus && cd thalamus

docker compose up -d           # the graph, on 127.0.0.1:8182; no licence, no account
uv sync --extra dev            # creates .venv with the package and its CLI
uv run thalamus init           # wire your editor, then verify what it wired

The graph answers a few seconds after up -d returns, because Docker publishes the port before the server finishes starting. docker compose ps says healthy when it is actually serving.

thalamus init installs at user scope, so the harness arms in every directory rather than only inside this checkout. It wires every supported harness by default; use --harness claude, --harness cursor or --harness codex for one. --dry-run reports without writing, and --check re-verifies any time.

Because user scope means outside this checkout, it lists what it will write and asks before writing: ~/.claude/settings.json, ~/.cursor/hooks.json and ~/.codex/hooks.json, ~/.claude.json (the MCP server), plus skill symlinks and one derived agent per expert. Pass --yes to skip the prompt in a script; a non-interactive stdin declines rather than assumes. thalamus init --uninstall takes all of it back out, removing only what it can prove it installed, and leaving your graph, ~/.thalamus/ and the transcript archive alone.

Then relaunch your editor

Hooks and the MCP server arm per process, so an already-running session picks up nothing. Quit and reopen your editor; /clear is not enough.

A new session should greet you with a memory prompt and its pinned scope. From there, memory builds itself. Distillation runs when a session ends, detached, and says nothing in your terminal. So have a real session, quit the editor, and ask:

uv run thalamus status         # sessions in the graph, and the last distillation run

The count going from 0 to 1 is the confirmation that it works. thalamus init --check answers the other half: whether the wiring that writes it is armed.

The full walkthrough, including what the first run looks like, is docs/getting-started.md.

What this release is

Thalamus runs from a clone, and git pull is the upgrade path. A wheel built from the tree installs outside a checkout: it finds its own hook scripts and skills, and its hooks run the CLI under the interpreter thalamus init records, and init gives it two example experts, and thalamus graph up brings up the graph from the compose file it ships. A version tag publishes it to PyPI as thalamus-memory (CONTRIBUTING.md, "Releasing"); the import name and the CLI stay thalamus.

One feature is experimental and off by default: frame themes, which render the pane inside artwork, behind thalamus console --frames PATH. Without the flag there are no controls and no key bindings, and no artwork ships.

What's live

• The graph. A property graph (Apache TinkerPop / TinkerGraph) with ten node kinds: Session, Claim, Thread, Source, Artifact, Chunk, Entity, Exchange, Trace and Agent, every one carrying provenance and a scope. Orphans and contract violations are rejected at write time.
• The evidence archive. Memory is bootstrapped from retained session transcripts, held in an immutable content-addressed store outside the repo. The graph is a view over that log that can be rebuilt from it: re-extract, never migrate.
• Curated ingestion. An expert's document half is fed one document at a time. thalamus ingest <url|path> --scope <expert> refuses bytes whose serving origin the scope's manifest does not allowlist, retains what survives the gate in the archive, and on --write lands it as a Source with the text indexed as Chunk vertices beside the claims drawn from it. --check runs that same path and stops at the model call, reporting the host that actually served the bytes for no model spend. The bytes are retained either way; the graph is what --write gates.
• Experts. Each scope is declared by a manifest in config/experts/ and nothing else. This repository's config/ holds five, and an installed wheel ships two examples; write a YAML file and you have another.
• Role boundaries. Where a scope is defined by what it must not produce, its manifest declares a write_boundary and a PreToolUse hook enforces it against the file-editing tools. The shipped qe manifest is the worked example: it holds the adversarial suite and is denied src/, so the scope that asserts against an implementation cannot quietly repair it. The reverse denial is in the ownership table, so no other scope can soften what it asserts either.
• Session pinning. One OS process, one immutable pin. thalamus pin <scope> hands the terminal to a session pinned to that scope. The MCP server reads the scope from its environment at startup and no tool accepts a scope argument, so a model cannot widen its own view by asking. Nor by shelling out: the graph client reaches the whole graph, so a PreToolUse guard keeps a pinned session off it and on the tools that confine a read to the pin.
• The console. Optional, and the part that needs tmux: it runs pinned sessions as tmux windows so all of them are addressable from one place. thalamus console serves them to a browser: a tab per window, the live pane, a composer, and one tap to spawn an expert in a project. It installs as a PWA on a phone over a tailnet.
• Consultations. Cross-expert questions ride single-use tickets where minting the ticket is writing the exchange record, and answers must cite nodes inside the consulted scope. Beside it, thalamus quick ask forks an expert's live session rather than cold-starting one.
• Rooms. Part of the console: a private set of live sessions whose members see and message each other and nobody else, enforced by a per-room config directory and an outbound guard.
• The eval loop. Every memory-tool call is logged as a Trace node, judged used or ignored against the retained transcript, and priced in injected tokens. Above it, a counterfactual harness runs one task with memory on, off and degraded in a confined worktree, graded by an oracle whose rungs are validated against a mutant set before any run is scored.
• Trust enforcement, first pass. The transcript-ingress floor down-tiers distilled claims that rest on pages fetched with the agent's web tools.

Status

Built and running: the graph, the archive, curated ingestion, experts and pinning, the console, consultations, rooms, and the eval loop's trace, attribution and cost layers.

In progress: counterfactual measurement at a scale that can settle whether recalled memory changes task outcomes. What the instrument shows today is that memory gets surfaced; that it improves results is not yet demonstrated, and saying so is part of the design. Computing trust across whole derivation chains, closing the shell-fetch and paraphrase gaps, and end-to-end audit chains come after.

Roadmap and open work live in GitHub issues and milestones.

Documentation

Layout

src/thalamus/
  substrate/   storage kernel: schema, Gremlin writer, Gremlin reader, query span tap
  contract/    the federation boundary: ontology, expert manifests, conformance
  console/     the optional browser/PWA control plane: tmux windows, rooms, dispatch
  archive/     immutable content-addressed store for retained evidence
  harness/     where it meets the agent: MCP server, hooks, skills, bootstrap, ingest
  eval/        trace tap, attribution, cost: the live-serving half of the eval loop.
               The counterfactual harness (task battery, arms, oracle) is research
               instrumentation; it lives in the private thalamus-eval companion repo
  arch/        the `architect` scope's instrument: a declared-policy import extractor
               and the structural metrics computed over it, gated in CI
  pulse/       live telemetry dashboard over the eval loop
arch/          model.yaml, the committed architecture model the gates check against
config/        expert manifests
ledger/        the claims ledger: one entry per documented commitment, pinned by
               digest to the section of source that keeps it true
docs/          user documentation
docker/        the confinement image a counterfactual arm runs inside
tools/         frame-theme authoring scripts (`--extra frames`)
tests/         the suite, including `tests/qe/`, the adversarial suite owned by `qe`

License

MIT. See LICENSE.