convez.ai
MCP ServerProdutividadeAvançado
wallter

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 GitHub
InicialPluginScore · de 0 a 100

Servidor 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-mcp

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
57%
Último commit
há 5 dias
Versão
—
Issues abertas
29
Contribuidores
1

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.

Python 3.10+ License: BSL 1.1 MCP Docs

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 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
ceremony_mode: "full"              # "full", "light", or "off"

MCP Tools (43)

CategoryToolsPurpose
Sessionsession_start, init, status, checkpoint, pre_compact_checkpoint, heartbeat, adopt_runRun lifecycle, progress tracking, and pin/liveness management
Learninglearn, learn_update, recall, knowledge_sync, claude_md_sync, instructions_syncKnowledge capture, retrieval, and instruction-file refresh
Qualitybuild_check, review, deliverVerification and delivery
Requirementsprd_create, prd_validate, prd_diffSpec-driven development with AARE-F PRDs
Ceremonyceremony_status, ceremony_approve, ceremony_revertWorkflow compliance
Code intelligencecode_search, code_symbol, code_index_update, before_edit_hint, codebase_risk_report, entity_risk_mapRepo-aware search, symbol lookup, and risk signals
Observabilityquery_events, surface_diff, mcp_security_statusEvent 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:

RoleAgentPurpose
Core Teamtrw-lead, trw-implementer, trw-tester, trw-researcher, trw-reviewer, trw-auditor, trw-adversarial-auditorOrchestration, TDD, testing, research, review, audit, spec-vs-code audit
Requirementstrw-prd-groomer, trw-requirement-writer, trw-requirement-reviewerPRD lifecycle specialists
Qualitytrw-traceability-checker, trw-code-simplifierTraceability 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

Ver o original no GitHub

Bom para

Relacionados