Documentation

Installation

Add AgenTrace to your agent's MCP config. Works with Claude Code, Cursor, Windsurf, Codex, Cline, and any MCP-compatible agent.

{
  "mcpServers": {
    "AgenTrace": {
      "command": "npx",
      "args": ["-y", "@theagentrace/mcp"],
      "env": {
        "AGENTRACE_API_KEY": "your_api_key_here"
      }
    }
  }
}

Get your API key from the dashboard after signing in.

How agents should use it

Add these instructions to your CLAUDE.md, system prompt, or agent rules.

# Memory — AgenTrace

At the start of every thread:
1. Call session_context() to load active project history
2. Call query_memory({ query: "<task topic>" }) before reading any file

During the thread — save immediately when you discover:
- An architectural decision and why it was made
- A risk, trap, or "do not touch" warning
- A bug root cause or fix
- A pattern or convention that isn't obvious from the code

Use quick_note() for fast captures. Use save_memory_node() for
structured findings with tags and status.

Claude Code — deferred tools

Claude Code registers MCP tools as deferred — the tool names appear in the available-tools list but their schemas are not loaded by default. Calling an AgenTrace tool without loading the schema first will fail with an InputValidationError.

Fix: add a UserPromptSubmit hook in your Claude Code settings that instructs the agent to fetch tool schemas before doing anything else. Once added, it fires automatically on every prompt — you never have to think about it again.

## AgenTrace — Claude Code setup

AgenTrace tools are deferred in Claude Code — schemas not loaded by default.
Before reading any file or calling any AgenTrace tool, run:

  ToolSearch("select:mcp__agentrace__session_context,mcp__agentrace__query_memory,
    mcp__agentrace__save_memory_node,mcp__agentrace__append_event,
    mcp__agentrace__link_memory_nodes,mcp__agentrace__get_node")

Then immediately call:
  mcp__agentrace__session_context()
  mcp__agentrace__query_memory({ query: "<task topic>" })

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo 'MANDATORY: AgenTrace tools are deferred. Call ToolSearch first, then session_context, then query_memory.'"
          }
        ]
      }
    ]
  }
}

Tool reference

session_context()

query_memory({
  query: "auth middleware decisions",
  limit: 5
})

save_memory_node({
  id: "decision:use-postgres",
  type: "decision",
  label: "Chose PostgreSQL over MongoDB",
  summary: "ACID guarantees and relational joins. Do not revisit.",
  status: "active",
  confidence: 0.95,
  tags: ["database", "architecture"]
})

quick_note({
  summary: "v1/auth.ts is dead — do not touch. Still receives 5% of prod traffic.",
  type: "risk",
  tags: ["v1", "deprecated"]
})

link_memory_nodes({
  from: "bug:auth-timeout",
  to: "decision:increase-jwt-expiry",
  label: "caused"
})

supersede_node({
  old_id: "decision:use-rest-api",
  new_node: {
    id: "decision:migrate-to-trpc",
    type: "decision",
    summary: "Moved from REST to tRPC. REST approach had too much boilerplate."
  }
})

append_event({
  type: "finding",
  summary: "Fixed rate limit bug on search — switched to X-Forwarded-For.",
  tags: ["bugfix", "search"],
  nodes: ["finding:rate-limit-fix"]
})

get_node({ id: "decision:use-postgres" })

Node types

Choose the type that best matches what you're saving. Type affects scoring — risks surface when the agent is about to do something dangerous, decisions surface when architecture is discussed.

What not to store

These create noise in retrieval and should be avoided:

• ✗File trees or directory listings — agents can run find/ls, these go stale immediately
• ✗Code snippets that belong in the file itself — if it's readable from the source, don't mirror it
• ✗Generic summaries of files — "this file handles auth" adds nothing a future agent can't derive
• ✗Things already in git history or comments
• ✗Temporary state or in-progress work — save the outcome, not the journey