Decision memory

trace-mcp includes a persistent decision knowledge graph that captures architectural decisions, tech choices, bug root causes, preferences, and conventions — linked to the code they’re about.

Why

Every conversation with an AI agent produces decisions that disappear when the session ends. Six months of daily AI use = thousands of decisions lost. General-purpose memory tools (MemPalace, OpenMemory, Mem0) store these as text. trace-mcp stores them linked to code symbols and files — so when you ask “what breaks if I change this?”, you also see why it was built that way.

What “why” actually looks like

The system tries to capture the kinds of reasoning that disappear from the diff but matter when someone returns to the code months later:

• The alternative that was rejected and the reason — “went with Postgres JSONB over a separate document store because transactional updates had to span relational and semi-structured data in the same write.” Without the rejected branch, future readers re-litigate the same choice.
• The constraint that forced the hand — legal, performance budget, deadline, an upstream dependency we don’t control. Captured as tradeoff decisions with the constraint named, so when the constraint disappears the decision is flagged as revisitable.
• The failure mode behind a fix — for bug_root_cause, what actually went wrong, not what got patched. “Request body parser ran before auth middleware, so unauthenticated payloads hit the DB,” not “added auth check.” The fix is in the diff; the failure mode isn’t.
• The thing that was tried first and didn’t work — recovered from session logs by mine_sessions, because agents rarely volunteer their own dead ends. This is the highest-value content and the easiest to lose without dedicated capture.
• The local convention being established — “all new endpoints go through withAuth even if the route looks public.” Stops the next agent from reinventing or violating it.

Each of these is linked to the symbol or file it’s about, so the next agent who touches that code sees the reasoning surface automatically through get_change_impact or plan_turn — they don’t have to know the decision exists to find it.

Architecture

              ┌──────────────────────────────────────────┐
              │              CAPTURE PATHS                │
              │                                            │
  add_decision│  remember_decision   │   mine_sessions     │
  (manual,    │  (live agent write,  │   (post-hoc, scans  │
   conf=1.0)  │   confidence-scored) │    JSONL logs,      │
              │                      │    pattern-matched) │
              └────────┬──────────────┬──────────┬─────────┘
                       │              │          │
                       ▼              ▼          ▼
              ┌──────────────────────────────────────────┐
              │  Memoir-style review queue                │
              │   confidence ≥ 0.75 → active (default)    │
              │   0.45 ≤ conf < 0.75 → pending review     │
              │   confidence < 0.45  → dropped            │
              │   (approve_decision / reject_decision)    │
              └────────────────┬──────────────────────────┘
                               │
                               ▼
              ┌──────────────────────────────────────────┐
              │  Decision Store (decisions.db)            │
              │  SQLite + FTS5 (porter stemming)          │
              │  ┌────────────┐  ┌────────────────────┐   │
              │  │ decisions  │  │  session_chunks    │   │
              │  │ code-linked│  │  cross-session     │   │
              │  │ temporal   │  │  content search    │   │
              │  │ branch-aware│  │                    │   │
              │  └────────────┘  └────────────────────┘   │
              └────────────────┬──────────────────────────┘
                               │
                               ▼
              ┌──────────────────────────────────────────┐
              │  Enrichment Layer                         │
              │  get_change_impact  → linked_decisions    │
              │  plan_turn          → related_decisions   │
              │  get_wake_up(resume) → active_decisions   │
              │  get_wake_up        → orientation context │
              └──────────────────────────────────────────┘

Decision types

Memoir-style review queue

Not everything an agent observes is worth keeping. The capture pipeline routes every write through a three-tier confidence gate so high-signal decisions enter the graph immediately while borderline ones queue for a human, and noise is dropped:

Both thresholds are configurable via the decisions.review_threshold and decisions.reject_threshold keys in config, or per-call on mine_sessions and remember_decision.

Manage the queue with approve_decision / reject_decision; inspect it with query_decisions { include_pending: true } or query_decisions { review_status: "pending" }. add_decision bypasses the gate (it’s the explicit, human-curated path — confidence is pinned to 1.0).

Confidence scoring

The score that drives the review queue combines a base prior with multiplicative boosts for signals that correlate with usefulness:

For mined decisions, the pattern’s intrinsic confidence (see Extraction patterns) is additionally multiplied by 1 + 0.05 × n where n is the number of context boosters (because, reason, pros and cons, alternative, architecture, design decision) found in the surrounding turn.

The implementation lives in src/memory/decision-confidence.ts.

MCP tools

Capture

Review queue

Read & query

Search & orientation

Code linkage

Decisions can be linked to:

• Symbols — symbol_id: "src/auth/provider.ts::AuthProvider#class" — any symbol in the code graph
• Files — file_path: "src/auth/provider.ts" — a specific file
• Services — service_name: "auth-api" — a service/subproject within the project

When linked, decisions automatically surface in code intelligence tools:

get_change_impact(symbol_id="src/auth/provider.ts::AuthProvider#class")
→ {
    ...impact analysis...,
    linked_decisions: [
      { id: 42, title: "Use Clerk for auth", type: "tech_choice",
        symbol: "src/auth/provider.ts::AuthProvider#class", when: "2025-06-01" }
    ]
  }

Temporal validity

Every decision has a valid_from timestamp (when it was made) and an optional valid_until (when it was superseded):

• Active decisions — valid_until IS NULL — currently in effect
• Invalidated decisions — valid_until IS NOT NULL — superseded but preserved for history

Query modes:

query_decisions()                              # active only (default)
query_decisions(as_of="2025-01-15T00:00:00Z")  # what was active on Jan 15
query_decisions(include_invalidated=true)       # full history

Service scoping

In projects with multiple services (subprojects), decisions can be scoped to a specific service:

add_decision(
  title="Use JWT for service-to-service auth",
  service_name="auth-api",
  type="tech_choice"
)

query_decisions(service_name="auth-api")     # only auth-api decisions
query_decisions()                            # all project decisions
get_decision_stats()                         # shows available_services

Extraction patterns

The conversation miner uses 8 regex-based patterns to extract decisions from assistant messages:

Context boosters (“because”, “reasoning”, “pros and cons”, “architecture”) increase confidence by 5% each.

Auto-tagging detects topics: auth, database, api, testing, performance, security, devops, typescript, refactoring, migration.

What we deliberately don’t record

Decision memory is for content that disappears when the chat log is gone. It explicitly avoids storing things that can be recovered from the code or git history:

• The diff itself — git log -p is authoritative.
• Who touched what — git blame and git shortlog answer this.
• Current code state — read the file; the index has an outline.

The mining pipeline also filters non-user content before it reaches the store. Block-tagged regions stripped during ingestion:

<command-message> and <command-name> are kept — those wrap real user slash-commands and are part of the conversation. Implementation: stripPrivacyTags in src/memory/conversation-miner.ts.

CLI

trace-mcp memory mine [--project=.] [--force] [--min-confidence=0.6]
trace-mcp memory index [--project=.] [--force]
trace-mcp memory search "query" [--project=.] [--limit=20]
trace-mcp memory decisions [--project=.] [--type=tech_choice] [--search="query"] [--json]
trace-mcp memory stats [--project=.] [--json]
trace-mcp memory timeline [--project=.] [--file=path] [--symbol=id]

Storage

All decision memory is stored in ~/.trace-mcp/decisions.db (SQLite, WAL mode). Tables:

• decisions — decision records with code linkage, temporal validity, service scoping
• decisions_fts — FTS5 virtual table for full-text search over decisions
• session_chunks — chunked conversation content from session logs
• session_chunks_fts — FTS5 virtual table for cross-session content search
• mined_sessions — tracking which sessions have been processed

Key columns on decisions:

Last updated: August 30, 2026