trw-mcp

MCP server for AI coding agents — persistent engineering memory, knowledge compounding, and spec-driven development workflows. Part of TRW Framework.

Every AI coding tool resets to zero. TRW preserves state across sessions via the .trw/ directory — session-start recall replays prior learnings at every new session.

Part of TRW Framework

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 <!-- inv:tools -->47<!-- /inv --> tools, <!-- inv:skills -->26<!-- /inv --> skills, <!-- inv:agents -->12<!-- /inv --> 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; iter-0..10 SWE-bench-single-shot measurements showed null (n=40/47). See docs/eval/iter-notes/iter-11-prospector-analysis.md.

The server also manages structured run tracking (phases, checkpoints, events), build verification (pytest + mypy), spec-driven development with AARE-F PRDs, CLAUDE.md auto-generation from high-impact learnings, and instruction-tool manifest validation that ensures agents only see tools they can actually call.

Dogfooding scale: 336 PRDs, 90 sprints, 9,200+ tests, 90% coverage. 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

See the full quickstart guide for Claude Code, Cursor, opencode, and Codex setup.

# Install from PyPI
pip install trw-mcp

# 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]"

# Deploy TRW to a project (must be a git repo)
trw-mcp init-project /path/to/your/repo

# Or add the MCP server to Claude Code manually
claude mcp add trw -- trw-mcp --debug

Deploy to a Project

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

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

This creates:

• .trw/ — learning memory, run state, configuration
• .mcp.json — MCP server connection for Claude Code
• CLAUDE.md — project instructions with TRW ceremony protocol
• .claude/hooks/ — ceremony enforcement hooks
• .claude/skills/ — workflow automation skills
• .claude/agents/ — specialized sub-agents

Configuration

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

# .trw/config.yaml — top settings (all optional, shown with defaults)
embeddings_enabled: false          # Enable vector search (requires [vectors] extra)
learning_max_entries: 5000         # Max learnings before auto-pruning
build_check_enabled: true          # Run pytest+mypy on trw_build_check
observation_masking: true          # Reduce verbosity in long sessions
progressive_disclosure: false      # Show tools progressively
ceremony_mode: "full"              # "full", "light", or "off"

MCP Tools (24)

24 tools covering the full AI coding assistant memory lifecycle. See tool reference docs for detailed parameter documentation.

Category	Tools	Purpose
Session	session_start, init, status, checkpoint, pre_compact_checkpoint, progressive_expand	Run lifecycle and progress tracking
Learning	learn, learn_update, recall, knowledge_sync, claude_md_sync	Knowledge capture and retrieval
Quality	build_check, review, trust_level, quality_dashboard, deliver	Verification and delivery
Requirements	prd_create, prd_validate	Spec-driven development with AARE-F PRDs
Ceremony	ceremony_status, ceremony_approve, ceremony_revert	Workflow compliance
Reporting	run_report, analytics_report, usage_report	Metrics and cost tracking

Skills (24)

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

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

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

Quality: /trw-audit · /trw-review-pr · /trw-simplify · /trw-dry-check · /trw-security-check · /trw-test-strategy

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

Agents (18)

Specialized sub-agents for Agent Teams — parallel execution with coordinated handoffs:

Role	Agent	Purpose
Core Team	trw-lead, trw-implementer, trw-tester, trw-researcher, trw-reviewer, trw-adversarial-auditor	Orchestration, TDD, testing, research, review, spec-vs-code audit
Requirements	trw-prd-groomer, trw-requirement-writer, trw-requirement-reviewer	PRD lifecycle specialists
Quality	trw-traceability-checker, trw-code-simplifier	Traceability and code health

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 framework overview at trwframework.com/docs/framework.

CLI Commands

trw-mcp init-project .                # Deploy TRW to a project
trw-mcp update-project .              # Update existing installation
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 export --format json          # Export learnings
trw-mcp uninstall .                   # Remove TRW from a project

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.py        # 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 Embeddings require the [vectors] extra: pip install 'trw-mcp[vectors]'. 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