trw-mcp

Give your coding agent a memory that carries over from one session to the next.

trw-mcp is a local MCP server for the coding agent you already use. Your agent writes down what it learns in a repository (patterns, gotchas, decisions) and gets the relevant pieces back when the next session starts. It also keeps run state and delivery checks, so work can be picked up where it stopped. One installer sets it up for Claude Code, Codex, Cursor, GitHub Copilot CLI, OpenCode, Antigravity CLI and Grok Build CLI.

Local-first · MCP-native · source-available (BSL 1.1)

Quick start · What's new in 9.x · Upgrading · Tools · Configuration · Network and security · Troubleshooting

Why TRW

A new coding-agent session usually starts without what the last one learned. It rediscovers the same repository quirks, retries the approach that failed last week, and asks again why a file is laid out the way it is.

With trw-mcp, the agent records short learnings as it works, gets up to three relevant ones back at the start of the next session, and can search for more. Checkpoints let a later session, or a different agent, resume a run. Your learnings and run state stay on your machine: learnings in one local store, run state in each project's .trw/ directory.

What sets it apart:

• More than memory. Recall, run state, build evidence, delivery checks and requirements tracing come from one server.
• One setup for many clients. The same install configures instructions, hooks, skills and agents for each supported client.
• Local by design. Memory lives in SQLite on your machine and runs without a cloud service.

What you get

• Memory across sessions. trw_learn records a learning; trw_session_start recalls once at session start and returns up to three short stubs; trw_recall searches on demand.
• Hybrid recall. Every recall uses keyword search; vector search joins it when embeddings are installed, which the installer does by default.
• One store for all your projects. A local memory daemon (from trw-memory) serves one store per user account; each checkout reads and writes its own namespace.
• Resumable runs. Phases, checkpoints, events and delivery records live in the project's .trw/ directory.
• Delivery checks. trw_build_check records the build and test results your agent ran (it runs nothing itself). By default trw_deliver refuses coding work with no passing build record.
• Requirements workflow. Write AARE-F PRDs, validate them, and trace requirements to code.
• Client setup. trw-mcp init-project writes each selected client's instruction file, MCP config, hooks, skills and agent definitions where that client supports them.

Quick start

Inside the git repository you want to set up, run:

curl -fsSL https://trwframework.com/install.sh | bash

Sign in or create a free account in the browser when asked, and the installer does the rest: it installs trw-mcp and trw-memory with semantic recall, caches the recall model, sets up the project for your client and brings over learnings from an older install.

Installer flags go after bash -s --, for example curl -fsSL https://trwframework.com/install.sh | bash -s -- --ide codex; --no-embeddings and --no-migrate work the same way. --allow-unauthenticated skips the account and installs the trw-mcp package only, without embeddings. What a signed-in install connects to is listed under Network and security.

Or install with pip (no account; migration and model caching are then up to you):

pip install trw-mcp 'trw-memory[embeddings]'   # drop the second package for keyword-only recall
cd /path/to/your/repo
trw-mcp init-project .                        # add --ide <id> to choose clients
trw-mcp doctor .                              # checks the install, clients and retrieval

Reconnect your MCP client afterwards (/mcp in Claude Code; restart the session elsewhere).

Supported clients (--ide id): Antigravity CLI (antigravity-cli), Claude Code (claude-code), Codex (codex), GitHub Copilot CLI (copilot), Cursor CLI (cursor-cli), Cursor IDE (cursor-ide), Grok Build CLI (grok) and OpenCode (opencode). --ide all sets up every client, which suits a repository shared across tools. Without --ide, init-project detects the client. Per-client details: trwframework.com/docs/clients.

Requirements: Python 3.11 to 3.14 and a git repository, on macOS (arm64, x86_64) or Linux with glibc (x86_64, aarch64). On Windows, run it inside WSL2, which works as Linux. Native Windows is not supported: the installer stops and points to WSL2. Alpine is not supported, because sqlite-vec publishes no musl wheel.

_{Alpha release: source-available under the Business Source License 1.1, free for any use except offering a competing commercial product, converting to Apache 2.0 on 2030-03-21. The API may still change.}

What's new in 9.x

• TRW progress in Claude Code's status line. Phase, checkpoint age, build, review and deliver evidence on one line; trw-mcp local status --json gives any client the same snapshot.
• A cap on dispatch fan-out. Opt in to dispatch_max_concurrent_children to limit how many dispatched agents run at once.
• Learning keeps working across upgrades. A memory daemon stricter than the server no longer blocks trw_learn and trw_recall.
• Upgrades say what they changed. update-project names every file it removes and every CLAUDE.md edit, and leaves an AGENTS.md shim alone.
• A complete installer log. The run log holds the whole install, and doctor names MCP servers still running pre-upgrade code.
• Share learnings from any host. trw-mcp sync push, pull and status share team learnings from hosts with no MCP server running, such as CI, headless agents and containers.
• Sensitive learnings stay home. Confidentiality labels decide what each surface shows: nothing labelled above team is pushed, backed up remotely or written to a tracked file.

Requires Python 3.11+ and trw-memory 5.2.1. 9.0.0 was a breaking release: read the upgrade notes and the CHANGELOG first.

Upgrading

From 8.x to 9.0.0:

1. Install trw-memory 5.2.0 first, then trw-mcp 9.0.0: pip install -U "trw-memory>=5.2,<6" and pip install -U "trw-mcp>=9,<10", then run trw-mcp update-project in each project and reconnect your MCP clients.
2. The trw-prd-new compatibility skill is gone: use /trw-prd-ready, which takes a feature description or an existing PRD.
3. Remove self_review_blocking from .trw/config.yaml if you set it; the key no longer exists.
4. Turn on team_sync_enabled if you want recall to search your team's learnings on the platform: a recall query no longer leaves the machine without it. Team learnings you pull are still recalled locally either way.

From 7.x to 8.0.0:

1. Use Python 3.11 or newer, then install trw-memory 5.0.0 first, then trw-mcp 8.0.0: pip install -U "trw-memory>=5,<6" and pip install -U "trw-mcp>=8,<9".
2. Run trw-mcp update-project in each project. It writes AGENTS.md for Claude Code, removes a TRW-only CLAUDE.md, and refreshes every client's instructions.
3. If you use formations, run trw-mcp formation comms-upgrade once per mailbox, from the formation's orchestrator session, to move it to schema v5.
4. Stop the old memory daemon (manual in 8.0.0), then restart the MCP server. Upgrading does not restart the running 7.x daemon. Until you stop it, the first memory call is refused with daemon_version_mismatch ... The user should stop the old daemon (process <pid>) ... Agents must not stop or remove it themselves; report this to the user., and the refusal touches no data; trw-mcp doctor names the pid too. Stop that process (after checking it is python -m trw_memory.server), or delete a stale ~/.trw/memory/daemon.json, and the next memory call starts a 5.0.0 daemon. The memory store migrates to schema v13 on first open, after one automatic backup of a store that already holds entries. trw-mcp doctor should then show memory_daemon PASS at version 5.0.0.

Every breaking change, with its migration, is in the CHANGELOG.

From 6.x to 7.0.0:

1. Upgrade both packages together. trw-mcp 7.0.0 needs a trw-memory 4.x memory daemon, and a 4.x daemon refuses a 3.x client by name.

   pip install -U "trw-mcp==7.0.0" "trw-memory[embeddings]==4.0.0"
   

2. Restart the memory daemon. A running 3.x daemon keeps serving until it exits. Stop the pid in daemon.json in the user memory directory ($TRW_USER_DIR/memory, else $XDG_DATA_HOME/trw/memory, else ~/.trw/memory); the next memory call starts a 4.0.0 daemon.

3. Fetch the models: trw-mcp models fetch. Runtime loads never download, and trw-memory 4.0.0 loads the embedding model at one pinned revision, so a cache filled by 3.x may not satisfy it.

4. Refresh each project: trw-mcp update-project --ide <id> (or --ide all; --dry-run previews). It rewrites hooks, skills, agents and instruction files that named tools that no longer exist.

5. Reconnect every MCP client (a client started before the upgrade keeps the old server), then run trw-mcp doctor. If its retrieval row counts stored vectors outside the active embedding space, run trw-mcp memory reembed --json and check that status is ok.

6. Check your memory store. trw-memory releases before 4.0.0 could corrupt a store shared by two processes, and 2.0.0, 3.0.0 and 3.1.0 could lose a new store's first writes. Run sqlite3 <store> 'pragma integrity_check' on the user store (memory.db in the directory from step 2) and on any project store (<project>/.trw/memory/memory.db); output other than ok reports a problem, and trw-memory restore --from-snapshot latest --db <path> (with every process using the store stopped) rebuilds it. A memory.db.corrupt.*.bak file beside the store from its first use may hold lost learnings; open it read-only before deleting it.

install-trw.py --upgrade covers steps 1 and 3, and step 4 only when the deployed framework is out of date. It never stops the memory daemon.

Also carried from 7.0.0, if you are coming from 6.x (every change is in the CHANGELOG):

• 51 tools became 15. Removed tools have no aliases: each is now a mode of a tool that stays, a trw-mcp command, or deleted. The CHANGELOG maps every name.
• trw_dispatch needs dispatch_tools_exposed: true in .trw/config.yaml; there is no per-call grant any more.
• One network switch. The old offline environment variable is gone: runtime model loads never download, and platform_contact_enabled: false turns off team sync.
• Retired config keys log a warning (list); a profile that still sets allowed_tools_by_phase fails validation.
• Rebuild the code index: run trw-mcp code index; the build deletes any legacy .trw/code-index/chunks.json itself.

How it works

• Processes. Each MCP client starts its own trw-mcp process over stdio. Memory calls go to one local memory daemon per user account, which the first memory call starts and which exits when idle.
• Where data lives. Run state and logs live in the project's .trw/; client files go where each client reads them. Learnings live in the daemon's store, ~/.trw/memory/memory.db (or under $TRW_USER_DIR or $XDG_DATA_HOME/trw when set), under the checkout's project_namespace, reached through the checkout's grant (.trw/runtime/memory-token).
• Tool surface. The surface is flat: every session sees the kernel plus every capability pack whose config flag is on (comms_enabled, dispatch_tools_exposed, assess_enabled). See the resolved surface with trw_status(detail="surface") or the CLI trw-mcp profile explain [--json].
• Lifecycle. TRW's method runs work through RESEARCH, PLAN, IMPLEMENT, VALIDATE, REVIEW and DELIVER, with exit checks between phases. The protocol is in FRAMEWORK.md and the lifecycle docs.

MCP tools, skills and agents

trw-mcp exposes 15 tools. The most used:

The tool reference covers the rest.

Skills (22 bundled). Workflows the agent loads only when invoked; the invocation syntax depends on the client. The ones you invoke directly:

• Delivery: /trw-deliver, /trw-commit, /trw-reflect
• Requirements: /trw-prd-ready
• Review and quality: /trw-audit, /trw-self-review, /trw-security-check, /trw-test-strategy, /trw-dry-check, /trw-delegate, /trw-plan-review
• Memory: /trw-learn, /trw-memory-audit, /trw-memory-optimize
• Framework: /trw-ceremony-guide, /trw-framework-check, /trw-project-health, /trw-feedback

Agents (8 bundled). Optional role definitions for clients that support delegation: trw-lead, trw-implementer, trw-researcher, trw-reviewer, trw-auditor, trw-adversarial-auditor, trw-prd-groomer and trw-requirement-reviewer. TRW does not need multiple agents; the same lifecycle works in one session.

CLI

trw-mcp init-project .                # set up TRW in a project
trw-mcp update-project .              # refresh an existing installation
trw-mcp doctor .                      # check the environment, clients and retrieval
trw-mcp check-instructions .          # instruction-to-tool parity (exits 1 on mismatch)
trw-mcp audit .                       # audit the TRW configuration
trw-mcp config-reference              # list the TRW_ variables for config settings
trw-mcp version-status                # compare package, framework and live-server versions
trw-mcp memory migrate --to user      # preview moving an old checkout store (--apply to move)
trw-mcp memory token                  # mint this checkout's memory grant
trw-mcp export --scope learnings      # export learnings as JSON (--format csv also works)
trw-mcp uninstall .                   # remove TRW from a project; ~/.trw is kept

Names starting with trw- inside client folders (.claude, .cursor, .opencode, .github, .agents and the rest) are TRW's: give your own skills, rules and agents another name, so TRW never treats them as its own files.

Configuration

Settings come from .trw/config.yaml, then ~/.trw/config.yaml, and TRW_-prefixed environment variables override both. Full reference: trwframework.com/docs/config.

# .trw/config.yaml (all optional, shown with their defaults)
embeddings_enabled: true           # trw-mcp's own embedding use (learn-time dedup); needs trw-memory[embeddings]
deliver_gate_mode: "block_coding"  # no passing build record blocks coding work or a run that changed files; "advisory" only warns
ceremony_mode: "full"              # or "light"
comms_enabled: true                # peer messaging tools (formation members only)
dispatch_tools_exposed: false      # tools that launch another installed agent client
assess_enabled: false              # the experimental trw_assess tool

A running server caches its settings, so reconnect the client after a change. A malformed .trw/config.yaml logs a warning and falls back to defaults; set TRW_CONFIG_STRICT=1 to fail closed instead.

Optional features:

• Peer messaging (comms_enabled, on by default) exposes trw_send and trw_inbox (trw_inbox's action parameter also enrolls, lists, and heartbeats among formation peers). Outside a formation they refuse and create no state. Messages are pull-based: a message does not wake an idle agent. Set comms_enabled: false to hide the tools.
• Dispatch (dispatch_tools_exposed, off by default) launches another installed agent client, for example for a second-opinion review (trw-mcp dispatch --client <client> ...). It does not install that client or supply its credentials. dispatch_child_trw_access (off by default) gives supported children TRW's own stdio MCP connection and no other host configuration. Containment differs by client: headless Antigravity, for example, still loads its own configured MCP servers, and TRW's macOS write-denial wrapper for it does not isolate network access. Check trw-mcp dispatch --help and the result's sandbox_verified field before relying on a read-only review.
• trw_assess (assess_enabled, off by default, experimental) returns calibrated probabilities for judgment calls. It is advisory. With the setting on and an OPENROUTER_API_KEY in the environment or the project .env, it sends the question and its state, with secrets redacted, to an allowlisted openrouter.ai endpoint.

None of these switches grants permission to modify files or bypass review gates, and peer messages are not trusted instructions.

Network and security

trw-mcp is local-first. Tool-call telemetry is recorded locally in .trw/logs/tool-telemetry.jsonl (telemetry_enabled, on by default). Learning content and usage telemetry are uploaded only if you turn on learning_sharing_enabled or platform_telemetry_enabled; both are off by default.

Platform connection. A signed-in install.sh install connects the project to the TRW platform: it adds platform_urls (https://api.trwframework.com) to .trw/config.yaml and stores your API key in .trw/credentials.yaml. Each session start compares the version the installer last recorded in .trw/installed-version.json with the running server, locally and without a network call, and suggests a reconnect if the recorded version is newer than the running server. With a platform URL configured, TRW also polls for team learnings every five minutes by default. The API key is attached only when the target host is on a trusted-host allowlist — the official platform host, or a host you add via ~/.trw/config.yaml (platform_trusted_hosts) or TRW_PLATFORM_TRUSTED_HOSTS; a project's own tracked .trw/config.yaml can point platform_urls/backend_url at any host, but doing so never makes that host trusted, so a cloned repo cannot redirect your key by editing tracked config. To turn the connection off, set platform_contact_enabled: false (or TRW_PLATFORM_CONTACT_ENABLED=false), or remove platform_urls (and platform_url or backend_url, if set) from .trw/config.yaml and ~/.trw/config.yaml. A pip install with trw-mcp init-project does not configure one.

These are the surfaces that can reach the network:

Model downloads are not a runtime behavior, so no consent flag governs them: learning_sharing_enabled and platform_telemetry_enabled govern uploads only. When a model is missing from the local Hugging Face cache, recall runs keyword-only and the embedding_egress row of trw-mcp doctor names the fix, trw-mcp models fetch. Loading a model that ships its own Python code is refused unless you set trw-memory's embedding_trust_remote_code: true; the default model does not need it.

Security defaults

The memory security settings (RBAC, the recall filter, canary and provenance) are daemon-wide, because one daemon serves every checkout. Set them as MEMORY_* variables in the environment the daemon starts from; a trw-mcp process that resolves a different value is refused and told which variable to set.

Trust boundary. A checkout's memory grant (.trw/runtime/memory-token) covers its own project namespace and your shared user:local namespace, so a checkout cannot reach another checkout's project namespace through the daemon, and the grant files are owner-only (0600, in a 0700 directory). The boundary is your OS user account: grants scope what a checkout may reach, they are not isolation from same-user processes. Any process running as the same user can read those files and the store itself, so run untrusted code under a different account.

For an air-gapped or compliance-sensitive setup: run trw-mcp models fetch once while online (or copy a populated model cache), set platform_contact_enabled: false and export TRW_CONFIG_STRICT=1, and leave platform_telemetry_enabled, learning_sharing_enabled and assess_enabled off. Then check that .trw/ directories are 0700, the daemon's store is 0600, and trw_session_start makes no outbound connection.

Environment variables

trw-mcp config-reference prints the TRW_ variable for every config setting, plus every variable read directly from the environment (never a TRWConfig field) — TRW_PROBE_ENABLED, for example — from one explicit registry kept in sync with the source by a dedicated test.

Troubleshooting

[Errno 2] No such file or directory on a TRW tool call. The server process exited. In Claude Code run /mcp to reconnect; in other clients, restart the session.

Claude Code searches for TRW tools before trw_session_start. The always-on tools are marked to load up front, but an explicit ENABLE_TOOL_SEARCH=true in Claude Code's environment overrides that and defers them all. Leave ENABLE_TOOL_SEARCH unset so the always-on tools load up front.

trw_session_start finds no learnings. Normal on first use. Learnings accumulate as the agent calls trw_learn.

Recall is keyword-only. Check the retrieval row of trw-mcp doctor, which names the missing piece and its fix. Usually trw-memory[embeddings] is not installed in the interpreter trw-mcp runs from (the daemon uses the same one). Install it, stop the memory daemon (send SIGTERM to the pid in daemon.json beside the store) so the next call starts a fresh one, and reconnect the client. embeddings_enabled: false is reported as a choice, not a fault.

Memory tools fail closed and print a memory migrate command. The checkout still has learnings in its old .trw/memory/memory.db, from before the per-user store. Run the printed command (trw-mcp memory migrate --to user previews; add --apply, which backs up first).

Memory is refused after moving a checkout. Mint a grant for the namespace it was pinned to: trw-mcp memory token --namespace <pinned namespace>.

update-project refuses because .trw/managed-artifacts.yaml is missing or invalid. Run trw-mcp uninstall --keep-memory, then trw-mcp init-project.

The memory store's -wal file keeps growing. A store reclaims WAL space only on SQLite 3.51.3 or newer (or the 3.44.6 and 3.50.7 backports). Older versions are safe but the file does not shrink. The memory_wal row of trw-mcp doctor reports the SQLite engine in use and measures the WAL of your resolved user store (TRW_USER_DIR, then XDG_DATA_HOME, then ~/.trw/memory/) — the same store the daemon writes to — not a per-checkout .trw/memory/memory.db-wal. When the engine is too old, the row names which of python3.14, python3.13, python3.12 and python3 on your PATH carry a qualifying SQLite (it probes those four within a 5-second budget and does not search further).

Debugging

trw-mcp --debug serve or TRW_LOG_LEVEL=DEBUG trw-mcp serve. Logs go to .trw/logs/trw-mcp-YYYY-MM-DD.jsonl.

Development

git clone https://github.com/wallter/trw-mcp.git && cd trw-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest tests/test_dedup_trw_learn.py -v  # one file while you work
pytest tests/ -q -n 8                    # the full suite before a change is done
mypy --strict src/trw_mcp/
ruff check src/

See CONTRIBUTING.md and, for vulnerability reports, SECURITY.md.

License

Business Source License 1.1: source-available, free for non-competing use, and it converts to Apache 2.0 on 2030-03-21. The LICENSE file has the exact terms.

Built by Tyler Wall · TRW Framework · Documentation · License