TRW MCP — Memória Persistente para Agentes de IA
wallter/trw-mcp
Memória persistente e compounding de conhecimento para codificação assistida por IA
Ver no GitHubServidor MCP que fornece memória de engenharia persistente para agentes de IA, registrando padrões, decisões arquiteturais e aprendizados de cada sessão de desenvolvimento. Integra rastreamento estruturado, verificação de build (pytest + mypy) e fluxos spec-driven com PRDs AARE-F. Faz parte do framework TRW, construído e testado em escala com milhares de testes no repositório monorepo.
Instalação
npx convez-ai wallter/trw-mcp1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Preservar aprendizados entre sessões de desenvolvimento com IA
- Rastrear decisões arquiteturais e gotchas em projetos longos
- Implementar fluxos spec-driven com validação de build automática
- Gerenciar estado e contexto de agentes de codificação entre execuções
Veredito

Ferramenta madura e dogfooded em escala (milhares de testes, centenas de PRDs) para times que usam agentes de IA em codificação. Honesto sobre limitações: não há evidência empírica de melhoria de taxa de sucesso vs. baseline (iter-0..10 SWE-bench null, n=40/47), mas oferece compounding de conhecimento estruturado e rastreabilidade robusta para fluxos spec-driven.
README
A tradução para o português deste README ainda está na fila.
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 43 tools, 25 skills, 12 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: 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
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 CodeCLAUDE.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
ceremony_mode: "full" # "full", "light", or "off"
MCP Tools (43)
| Category | Tools | Purpose |
|---|---|---|
| Session | session_start, init, status, checkpoint, pre_compact_checkpoint, heartbeat, adopt_run | Run lifecycle, progress tracking, and pin/liveness management |
| Learning | learn, learn_update, recall, knowledge_sync, claude_md_sync, instructions_sync | Knowledge capture, retrieval, and instruction-file refresh |
| Quality | build_check, review, deliver | Verification and delivery |
| Requirements | prd_create, prd_validate, prd_diff | Spec-driven development with AARE-F PRDs |
| Ceremony | ceremony_status, ceremony_approve, ceremony_revert | Workflow compliance |
| Code intelligence | code_search, code_symbol, code_index_update, before_edit_hint, codebase_risk_report, entity_risk_map | Repo-aware search, symbol lookup, and risk signals |
| Observability | query_events, surface_diff, mcp_security_status | Event history, surface diffs, and security status |
Skills (25)
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-self-review · /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 (12)
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-auditor, trw-adversarial-auditor | Orchestration, TDD, testing, research, review, audit, 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/ # 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