thalamus-memory 0.1.0__tar.gz

thalamus_memory-0.1.0/.gitignore

@@ -0,0 +1,43 @@
+# The graph and the evidence archive are PRIVATE and are NEVER shipped. Every
+# install is fresh, for everyone: the graph is one operator's session history,
+# and the archive holds their retained transcripts verbatim. Both live outside
+# the tree by design (a named Docker volume; ~/.thalamus/), so these patterns
+# guard against a stray `snapshot --path ./…` or a hand-copied archive rather
+# than against normal operation.
+# Anchored on purpose: an unanchored `archive/` would swallow the archive
+# *module* under src/, and `thalamus-graph*` would swallow the server's
+# config/thalamus-graph.groovy. Both are tracked code.
+*.kryo
+*.gryo
+/thalamus-graph-data/
+/archive/
+/.thalamus/
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+.venv/
+dist/
+*.egg-info/
+.ruff_cache/
+.pytest_cache/
+
+# Node
+frontend/node_modules/
+frontend/.vite/
+frontend/dist/
+.idea/
+
+# Derived pinned-agent definitions (thalamus pin) — the manifest is the source of truth
+.claude/agents/thalamus-*.md
+
+# Concurrent-session worktrees and per-machine harness settings. Ignored here rather
+# than only in .git/info/exclude because hatchling's sdist walk reads .gitignore and
+# nothing else: without these, `uv build` sweeps every in-progress branch checkout and
+# the local permission list into a publishable archive.
+.claude/worktrees/
+.claude/settings.local.json
+
+# qe findings — session-generated triage and corpus drafts, not the shipped suite.
+/tests/qe/findings/

thalamus_memory-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jackson Porter
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

thalamus_memory-0.1.0/PKG-INFO

@@ -0,0 +1,318 @@
+Metadata-Version: 2.5
+Name: thalamus-memory
+Version: 0.1.0
+Summary: Federated graph memory for coding agents — with a trust model and a measured utility loop
+Project-URL: Homepage, https://github.com/Ybx-jp/thalamus
+Project-URL: Repository, https://github.com/Ybx-jp/thalamus
+Project-URL: Issues, https://github.com/Ybx-jp/thalamus/issues
+Author: Jackson Porter
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,evaluation,gremlin,knowledge-graph,llm,memory
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.139.0
+Requires-Dist: fastmcp>=3.4.0
+Requires-Dist: gremlinpython<3.8,>=3.7
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: uvicorn[standard]>=0.51.0
+Provides-Extra: dev
+Requires-Dist: claims-ledger>=0.0.4; extra == 'dev'
+Requires-Dist: httpx>=0.28.1; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-xdist>=3.6; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: ty==0.0.74; extra == 'dev'
+Provides-Extra: frames
+Requires-Dist: numpy>=2.1; extra == 'frames'
+Requires-Dist: pillow>=10.0; extra == 'frames'
+Requires-Dist: scipy>=1.14; extra == 'frames'
+Provides-Extra: nli
+Requires-Dist: sentence-transformers>=3.3; extra == 'nli'
+Requires-Dist: torch>=2.5; extra == 'nli'
+Requires-Dist: transformers>=4.46; extra == 'nli'
+Provides-Extra: pdf
+Requires-Dist: pypdf>=5.0; extra == 'pdf'
+Description-Content-Type: text/markdown
+
+# 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](#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](docs/concepts.md). 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.<!-- (A0051, cites-as-live) -->
+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.<!-- (A0052, cites-as-live) -->
+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.<!-- (A0054, cites-as-live) -->
+
+### 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.<!-- (A0001, cites-as-live) -->
+Asking another expert is a recorded consultation, never a search that happens to reach
+across.<!-- (A0094, cites-as-live) -->
+
+### 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.<!-- (A0025, cites-as-live) -->
+
+### You can see what memory cost
+
+Every memory lookup is logged<!-- (A0097, cites-as-live) -->
+and priced. `thalamus pulse` serves a live dashboard of what retrieval actually
+cost.<!-- (A0085, cites-as-live) -->
+
+## 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
+
+| | Why |
+|---|---|
+| **Docker** | runs the graph (Gremlin Server on TinkerGraph) |
+| **Python ≥3.11** and [**uv**](https://docs.astral.sh/uv/) | the package and its CLI |
+| **jq** | every hook parses its stdin with it; without it the hook layer dies silently |
+| **A coding-agent CLI**: Claude Code (`claude`), Cursor (`agent`), codex (`codex`), or any mix | distillation shells out to it |
+
+The console additionally needs **tmux**: it runs pinned sessions as tmux windows
+([docs/console.md](docs/console.md)).
+
+### Install
+
+```bash
+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:
+
+```bash
+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](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.<!-- (A0086, cites-as-live) -->
+  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.<!-- (A0087, cites-as-live) -->
+  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<!-- (A0088, cites-as-live) -->,
+  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.<!-- (A0089, cites-as-live) -->
+  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.<!-- (A0004, cites-as-live) -->
+  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.<!-- (A0091, cites-as-live) -->
+  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.<!-- (A0092, cites-as-live) -->
+  The reverse denial is in the ownership table, so no other scope can soften what it
+  asserts either.<!-- (A0093, cites-as-live) -->
+- **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<!-- (A0148, cites-as-live) -->,
+  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.<!-- (A0094, cites-as-live) -->
+  Beside it, `thalamus quick ask` forks an expert's live session rather than
+  cold-starting one.<!-- (A0063, cites-as-live) -->
+- **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.<!-- (A0096, cites-as-live) -->
+- **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.<!-- (A0097, cites-as-live) -->
+  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](https://github.com/Ybx-jp/thalamus/issues).
+
+## Documentation
+
+| | |
+|---|---|
+| [Getting started](docs/getting-started.md) | Install, first run, and what each step should look like |
+| [Concepts](docs/concepts.md) | Scopes, experts, the federation contract, trust tiers, distillation |
+| [CLI reference](docs/cli.md) | Every command |
+| [The console](docs/console.md) | Driving your pinned sessions from your phone: the PWA, reaching it off the box, keeping it up |
+| [Contributing](CONTRIBUTING.md) | Tests, conventions, how the pieces fit |
+
+## 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](LICENSE).

thalamus_memory-0.1.0/README.md

@@ -0,0 +1,271 @@
+# 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](#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](docs/concepts.md). 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.<!-- (A0051, cites-as-live) -->
+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.<!-- (A0052, cites-as-live) -->
+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.<!-- (A0054, cites-as-live) -->
+
+### 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.<!-- (A0001, cites-as-live) -->
+Asking another expert is a recorded consultation, never a search that happens to reach
+across.<!-- (A0094, cites-as-live) -->
+
+### 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.<!-- (A0025, cites-as-live) -->
+
+### You can see what memory cost
+
+Every memory lookup is logged<!-- (A0097, cites-as-live) -->
+and priced. `thalamus pulse` serves a live dashboard of what retrieval actually
+cost.<!-- (A0085, cites-as-live) -->
+
+## 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
+
+| | Why |
+|---|---|
+| **Docker** | runs the graph (Gremlin Server on TinkerGraph) |
+| **Python ≥3.11** and [**uv**](https://docs.astral.sh/uv/) | the package and its CLI |
+| **jq** | every hook parses its stdin with it; without it the hook layer dies silently |
+| **A coding-agent CLI**: Claude Code (`claude`), Cursor (`agent`), codex (`codex`), or any mix | distillation shells out to it |
+
+The console additionally needs **tmux**: it runs pinned sessions as tmux windows
+([docs/console.md](docs/console.md)).
+
+### Install
+
+```bash
+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:
+
+```bash
+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](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.<!-- (A0086, cites-as-live) -->
+  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.<!-- (A0087, cites-as-live) -->
+  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<!-- (A0088, cites-as-live) -->,
+  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.<!-- (A0089, cites-as-live) -->
+  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.<!-- (A0004, cites-as-live) -->
+  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.<!-- (A0091, cites-as-live) -->
+  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.<!-- (A0092, cites-as-live) -->
+  The reverse denial is in the ownership table, so no other scope can soften what it
+  asserts either.<!-- (A0093, cites-as-live) -->
+- **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<!-- (A0148, cites-as-live) -->,
+  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.<!-- (A0094, cites-as-live) -->
+  Beside it, `thalamus quick ask` forks an expert's live session rather than
+  cold-starting one.<!-- (A0063, cites-as-live) -->
+- **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.<!-- (A0096, cites-as-live) -->
+- **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.<!-- (A0097, cites-as-live) -->
+  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](https://github.com/Ybx-jp/thalamus/issues).
+
+## Documentation
+
+| | |
+|---|---|
+| [Getting started](docs/getting-started.md) | Install, first run, and what each step should look like |
+| [Concepts](docs/concepts.md) | Scopes, experts, the federation contract, trust tiers, distillation |
+| [CLI reference](docs/cli.md) | Every command |
+| [The console](docs/console.md) | Driving your pinned sessions from your phone: the PWA, reaching it off the box, keeping it up |
+| [Contributing](CONTRIBUTING.md) | Tests, conventions, how the pieces fit |
+
+## 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](LICENSE).