trw-mcp

Persistent engineering memory for AI coding agents — an MCP server for cross-session recall, evidence-backed delivery, and spec-driven development. Part of TRW Framework.

Release status: Alpha and source-available under BSL 1.1. The current package is suitable for evaluation and dogfooding, but it does not claim a production-stable API or support SLA.

Coding-agent sessions are usually stateless. TRW keeps project knowledge in .trw/ and recalls relevant learnings when the next session starts.

Quick start · Core tools · Configuration · Security and network behavior · Development

How it fits

trw-mcp is the MCP server component of TRW (The Real Work) — a methodology layer for AI-assisted development that turns each coding session's discoveries into permanent institutional knowledge. It works alongside trw-memory, the standalone memory engine.

• trw-mcp (this repo): MCP server with 48 tools, 25 skills, 11 agents
• trw-memory: Standalone memory engine with hybrid retrieval, scoring, and lifecycle

What it does

trw-mcp is a Model Context Protocol server that gives AI coding agents persistent engineering memory. It records what you learn during development sessions — patterns, gotchas, architecture decisions — and recalls relevant knowledge at the start of every new session. Over time, your AI coding assistant accumulates captured learnings in .trw/ and recalls them at session start. Whether this yields measurable task-completion lift is an open empirical question; early SWE-bench single-shot measurements (n=40/47) showed null. See the verification docs for the current methodology and evidence posture.

Beyond memory, the server provides:

• Run lifecycle — phases, checkpoints, events, resumable state, and delivery records.
• Verification gates — project-native build evidence and structured review/delivery checks.
• Requirements workflows — AARE-F PRDs, validation, and requirement-to-code traceability.
• Client integration — generated instruction files, hooks, skills, and capability-aware tool exposure for supported coding clients.
• Code intelligence — lexical/symbol search, before-edit context, dependency relationships, and risk signals.

Dogfooding scale: thousands of tests across hundreds of PRDs, dogfooded across the TRW monorepo (coverage gate enforced at 80%, 90% target for new code). This codebase was built by AI agents using TRW. Scale proves the framework is usable at volume; whether it improves outcomes vs baseline is measured via the eval bench, not inferred from these counts.

Quick Start

Requires Python 3.10+ and a Git repository. The installer supports Claude Code, Codex, Cursor, OpenCode, Copilot, and Antigravity; use --ide all when a repository is shared across clients. See the full quickstart guide for client-specific setup.

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

# Bootstrap the current repository (client is auto-detected)
cd /path/to/your/repo
trw-mcp init-project .

# Confirm the installation and resolved client surfaces
trw-mcp doctor .

Manual / advanced install

# Install from PyPI (the [vectors] extra bundles sqlite-vec so vector search
# works out of the box; add [embeddings] for sentence-transformers, several
# hundred MB with torch — opt-in given its size)
pip install 'trw-mcp[vectors]'

# Or install from source
git clone https://github.com/wallter/trw-mcp.git
cd trw-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

Supported interpreters

trw-mcp is tested on CPython 3.10 through 3.14 (this repository's own development interpreter is CPython 3.14.7). The interpreter's bundled SQLite matters too: the memory store only RECLAIMS WAL space on SQLite >= 3.51.3 (or the 3.44.6 / 3.50.7 backports). Below that, checkpoints still run and the store is safe, but the -wal file grows without shrinking — trw-mcp doctor's memory_wal row reports the engine in use and names the interpreters on your PATH that would qualify. The driver is selected by trw-memory at import, ranking the interpreter's SQLite against an installed pysqlite3 so an older wheel can never replace a newer engine. The optional [sqlite-fix] extra pulls pysqlite3-binary on x86_64 Linux only; no published wheel currently bundles a qualifying SQLite.

Deploy to a Project

trw-mcp init-project bootstraps the full TRW framework in any git repository. Full configuration reference at trwframework.com/docs/config.

trw-mcp init-project .              # current directory
trw-mcp init-project /path/to/repo  # specific project
trw-mcp init-project . --ide codex  # force Codex bootstrap
trw-mcp init-project . --force      # overwrite existing files

Every installation creates .trw/ plus the Claude-compatible baseline used by the core bootstrap (.mcp.json, CLAUDE.md, and .claude/ hooks, skills, and agent definitions). The selected client integration then adds its own instruction, MCP, hook, skill, and agent surfaces where supported. Bundled skills and agent definitions are runtime inputs to init-project and update-project, not examples that can be discarded. Managed updates preserve user-authored content where the target format supports safe merging; review --force before using it in a customized repository.

Configuration

Settings via environment variables (prefix TRW_) or .trw/config.yaml. Full reference at trwframework.com/docs/config.

# .trw/config.yaml — top settings (all optional, shown with defaults)
embeddings_enabled: true           # Vector search on by default (install the [vectors] extra to use it)
learning_max_entries: 500          # Max learnings before auto-pruning
build_check_enabled: true          # Run pytest+mypy on trw_build_check
deliver_gate_mode: "block_coding"  # Block delivery for coding/rca/eval tasks without a passing build record;
                                   # set to "advisory" to restore warn-only posture (changed 2026-06-10)
observation_masking: true          # Reduce verbosity in long sessions
ceremony_mode: "full"              # "full" or "light"

Telemetry & network behavior

trw-mcp is local-first: with the default configuration it persists everything under your project's .trw/ directory and makes no outbound network calls except the optional embedding-model download described below. There is no built-in usage tracking, phone-home, or content upload unless you explicitly enable it.

What can touch the network, when, and how to turn it off

With TRW_OFFLINE=1 set, session_start makes zero huggingface.co calls — a testable invariant for air-gapped deployments. Since the cache-first resolution landed, a warm cache reaches the same zero-call result with no switch set at all.

Embedding egress is independent of the consent flags. learning_sharing_enabled and platform_telemetry_enabled govern learning-content publishing and usage telemetry only; neither one gates the model fetch. What governs embedding egress is the local cache plus the offline switches (TRW_OFFLINE / HF_HUB_OFFLINE) and trw-memory's local_only. Run trw-mcp doctor to read the current state — its embedding_egress row reports the cache state (complete/incomplete/absent) and the effective posture (cache-first, offline-forced, or network-capable).

Loading a model that ships its own Python modules is refused unless you set trw-memory's embedding_trust_remote_code: true; the shipped default model does not need it.

Cross-client messaging and dispatch (opt-in)

To enable the existing collaboration tools, merge these top-level keys into this project's .trw/config.yaml (do not replace your other settings):

comms_enabled: true
dispatch_tools_exposed: true
dispatch_child_trw_access: true

All three default to false and can be enabled independently:

• comms_enabled enables peer enrollment, sending and inbox operations (trw_peers, trw_send, trw_inbox). Messaging is pull-based: a message does not wake an idle agent or guarantee when it will read the inbox.
• dispatch_tools_exposed advertises the dispatch tool pack. Dispatch launches another installed agent client; exposing the tools does not install that client or supply its credentials.
• dispatch_child_trw_access gives supported dispatched children only TRW's own stdio MCP connection. It does not import host hooks or other client configuration. For clients without an MCP argv channel, this config default falls back to no TRW access; an explicit per-call --with-trw / with_trw=True request is refused. Reviewer posture has its own restricted TRW connection and cannot be combined with with_trw=True. Nested-launch guards remain in force.

Restart each client's TRW MCP connection, or start a new client session, after changing configuration: an already-running server caches its settings. Environment variables such as TRW_COMMS_ENABLED override YAML; project settings override ~/.trw/config.yaml. Set TRW_CONFIG_STRICT=1 in the server's environment to fail closed on invalid configuration rather than falling back with a warning.

To opt out again, set the corresponding keys to false, remove any conflicting environment overrides, and restart the connections. These switches do not grant permission to modify files, bypass review gates, or treat peer messages as trusted instructions.

Environment-variable inventory

A malformed .trw/config.yaml always emits a WARNING (and a stderr notice) rather than being silently discarded; set TRW_CONFIG_STRICT=1 to make the load fail closed so security overrides are never dropped unnoticed.

Security defaults

Enterprise hardening recipe

For an air-gapped or compliance-sensitive deployment:

export TRW_OFFLINE=1            # no huggingface.co egress; keyword-only recall
export TRW_CONFIG_STRICT=1      # malformed config fails closed, never silently reverts
# Leave telemetry + learning-sharing at their secure defaults:
#   platform_telemetry_enabled: false
#   learning_sharing_enabled:   false

Then verify: .trw/ dirs are 0700, memory.db is 0600, and no outbound connection is attempted at session_start.

MCP Tools (48)

The table below covers the most-used tools out of the full 48. For the complete, always-current list run trw-mcp config-reference or browse the tool reference docs.

Skills (25)

Slash-command workflows — zero tokens until triggered. Full skill reference at trwframework.com/docs.

Sprint & Delivery: /trw-sprint-init · /trw-sprint-finish · /trw-deliver · /trw-commit · /trw-reflect

Requirements: /trw-prd-new · /trw-prd-ready · /trw-prd-groom · /trw-prd-review · /trw-exec-plan

Quality: /trw-audit · /trw-self-review · /trw-delegate · /trw-dry-check · /trw-security-check · /trw-test-strategy

Framework: /trw-framework-check · /trw-project-health · /trw-memory-audit · /trw-memory-optimize

Agents (11)

Optional specialized agent definitions for clients and harnesses that support delegation. TRW does not require multi-agent execution; the same lifecycle works sequentially.

The 6-Phase Model

TRW implements a structured execution lifecycle: RESEARCH → PLAN → IMPLEMENT → VALIDATE → REVIEW → DELIVER with phase gates, build checks, adversarial audits, and delivery ceremony. See FRAMEWORK.md for the full specification, or read the lifecycle overview at trwframework.com/docs/lifecycle.

CLI Commands

trw-mcp init-project .                # Deploy TRW to a project
trw-mcp update-project .              # Update existing installation
trw-mcp doctor .                      # Diagnose environment and client setup
trw-mcp check-instructions .          # Validate instruction-tool parity (exit 1 on mismatch)
trw-mcp audit .                       # Audit TRW configuration
trw-mcp config-reference              # Print all TRW_ environment variables
trw-mcp version-status                # Compare package, framework, and live-server versions
trw-mcp export --format json          # Export learnings
trw-mcp uninstall .                   # Remove TRW from a project

Headless Antigravity reviews

Use TRW's dispatcher rather than invoking agy -p directly:

trw-mcp dispatch --client agy --cwd /path/to/repo \
  --prompt-file /path/to/review.txt --no-with-trw --json --verify-sandbox

Select an installed model with --model if needed. Headless Antigravity can exit zero without doing a review when its tool permissions require a prompt. TRW classifies that empty/denied result as unsuccessful; inspect ok, silence_reason, and sandbox_verified, not only the child exit code.

On macOS, TRW pairs its headless read permission allowance with a host sandbox-exec filesystem-write denial. Do not copy the allowance into a raw CLI invocation or disable permissions globally. Without the host wrapper, TRW withholds that allowance. --verify-sandbox costs an additional model call and checks file reads and attempted writes in a disposable fixture.

This supports file-reading reviews, not unrestricted shell-based testing: Antigravity commands that initialize helper files can fail under write denial. The bound does not isolate network access or the client's existing MCP servers. Antigravity does not support TRW's enforced reviewer MCP posture or explicit child TRW injection; --no-with-trw prevents requesting injection, not loading the client's own configured servers. A review role prompt is not an additional security boundary.

Development

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -v --cov=trw_mcp --cov-report=term-missing

# Type checking (strict mode)
mypy --strict src/trw_mcp/

# Targeted testing during development
pytest tests/test_tools_learning.py -k "test_recall" -v

Architecture

src/trw_mcp/
  server/             # FastMCP entry point, middleware chain
  bootstrap/          # init-project: deploy TRW to target repos
  models/             # Pydantic v2 models (config, run, learning, etc.)
  tools/              # MCP tool implementations
  state/              # State management (persistence, validation, analytics)
  middleware/         # FastMCP middleware (ceremony, observation masking, response optimizer)
  telemetry/          # Telemetry pipeline (models, sender, anonymizer)
  data/               # Bundled hooks, skills, agents for init-project

Troubleshooting

MCP connection error: "[Errno 2] No such file or directory" The MCP server process crashed. In Claude Code, type /mcp to reconnect. For other clients, restart your CLI tool.

trw_session_start() returns "No learnings found" This is normal on first use — learnings accumulate as you work. Call trw_learn() to save discoveries, then trw_deliver() to persist them.

stale .trw/ state after upgrading Run trw-mcp update-project . to migrate your project state to the latest schema. If issues persist, backup and re-initialize with trw-mcp init-project . --force.

Embeddings not working despite embeddings_enabled=true Vector search requires the [vectors] extra (sqlite-vec) — every install path (install.sh, pip, pipx, uv tool) requests it by default, so this is normally already installed. If it is missing (e.g. an old install predating the bundling fix, or --no-sqlite-vec was passed), run pip install 'trw-mcp[vectors]' and reconnect the MCP client. Without it, vector search silently degrades to keyword-only.

Debugging

Enable debug logging:

trw-mcp --debug serve              # Debug mode with file logging
TRW_LOG_LEVEL=DEBUG trw-mcp serve  # Via environment variable

Logs are written to .trw/logs/trw-mcp-YYYY-MM-DD.jsonl.

License

Business Source License 1.1 — source-available, free for non-competing use. Converts to Apache 2.0 on 2030-03-21. See the full license terms.

Built by Tyler Wall · TRW Framework · Documentation · License