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.
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 25 tools, 24 skills, 12 agents
- trw-memory: Standalone memory engine with hybrid retrieval, scoring, and lifecycle
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.
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 --debugtrw-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 filesThis creates:
.trw/— learning memory, run state, configuration.mcp.json— MCP server connection for Claude CodeCLAUDE.md— project instructions with TRW ceremony protocol.claude/hooks/— ceremony enforcement hooks.claude/skills/— workflow automation skills.claude/agents/— specialized sub-agents
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"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 |
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
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 |
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.
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# 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" -vsrc/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
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.
Enable debug logging:
trw-mcp --debug serve # Debug mode with file logging
TRW_LOG_LEVEL=DEBUG trw-mcp serve # Via environment variableLogs are written to .trw/logs/trw-mcp-YYYY-MM-DD.jsonl.
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