AgentRecall

AgentRecall v3.3.27 — Usage Guide

AgentRecall is a persistent memory system with 6 MCP tools. This guide describes how and when to use them.

Setup

AgentRecall requires the MCP server to be running. If tool calls fail with "unknown tool", the human needs to install it first.

Installation (human runs once)

Claude Code:

claude mcp add --scope user agent-recall -- npx -y agent-recall-mcp

Cursor (.cursor/mcp.json):

{ "mcpServers": { "agent-recall": { "command": "npx", "args": ["-y", "agent-recall-mcp"] } } }

VS Code / GitHub Copilot (.vscode/mcp.json):

{ "servers": { "agent-recall": { "command": "npx", "args": ["-y", "agent-recall-mcp"] } } }

Windsurf (~/.codeium/windsurf/mcp_config.json):

{ "mcpServers": { "agent-recall": { "command": "npx", "args": ["-y", "agent-recall-mcp"] } } }

Codex:

codex mcp add agent-recall -- npx -y agent-recall-mcp

Hermes Agent (~/.hermes/config.yaml):

mcp_servers:
  agent-recall:
    command: npx
    args: ["-y", "agent-recall-mcp"]

Roo Code (.roo/mcp.json):

{ "mcpServers": { "agent-recall": { "command": "npx", "args": ["-y", "agent-recall-mcp"] } } }

Any MCP-compatible agent:

command: npx
args: ["-y", "agent-recall-mcp"]
transport: stdio

Tools

AgentRecall provides these MCP tools:

session_start

When: Beginning of a session, to load prior context.

What it returns:

How to use the response: 1. Read identity to calibrate your tone and approach 2. Read insights — these are battle-tested lessons. Follow them. 3. Read watch_for — these are patterns where you've been wrong before on this project. Adjust your approach. 4. Read recent to understand where the last session left off 5. Present a brief to the human: project name, last session summary, relevant insights

Example call:

session_start({ project: "auto" })

remember

When: You learn something worth keeping. A decision, a bug fix, an insight, a session note.

What it does: Auto-classifies your content and routes it to the right store:

You do NOT need to decide where it goes. Just describe what to remember.

How to use:

remember({
  content: "We decided to use GraphQL instead of REST because the frontend needs flexible queries",
  context: "architecture decision"    // optional hint, improves routing
})

Returns: routed_to (which store), classification (content type), auto_name (semantic slug generated)

recall

When: You need to find something from past sessions. A decision, a pattern, a lesson.

What it does: Searches ALL stores at once using Reciprocal Rank Fusion (RRF) — each source (palace, journal, insights) ranks internally, then positions merge so no single source dominates. Journal entries decay fast via Ebbinghaus curve (S=2 days); palace entries are near-permanent (S=9999). Returns ranked results with stable IDs.

How to use:

recall({ query: "authentication design", limit: 5 })

Feedback: After using results, rate them. Ratings use a Bayesian Beta model — the mathematically optimal estimate of true usefulness:

recall({
  query: "auth patterns",
  feedback: [
    { id: "abc123", useful: true },   // Beta(2,1) → ×1.33 next time
    { id: "def456", useful: false }   // Beta(1,2) → ×0.67 next time
  ]
})

Feedback is query-aware — rating something "useless" for one query doesn't penalize it for unrelated queries.

session_end

When: End of session, after work is done.

What it does in one call:

How to use:

session_end({
  summary: "Built auth module with JWT refresh rotation. Fixed CORS bug.",
  insights: [
    {
      title: "JWT refresh tokens need httpOnly cookies — localStorage is vulnerable",
      evidence: "XSS attack vector discovered during security review",
      applies_when: ["auth", "jwt", "security", "cookies"],
      severity: "critical"
    }
  ],
  trajectory: "Next: add rate limiting to API endpoints"
})

Rules for insights:

check

When: Before executing a complex task where you might misunderstand the human's intent.

What it does:

Two-call pattern:

Call 1 — before work:

check({
  goal: "Build REST API for user management",
  confidence: "medium",
  assumptions: ["User wants REST, not GraphQL", "CRUD endpoints", "PostgreSQL backend"]
})

Read the watch_for response. If it says "You've been corrected on API style 3 times", ASK the human before proceeding.

Call 2 — after human corrects (if they do):

check({
  goal: "Build REST API for user management",
  confidence: "high",
  human_correction: "Actually wants GraphQL, not REST",
  delta: "API style preference — assumed REST, human prefers GraphQL"
})

This feeds the predictive system. Future agents on this project will get warnings.

Session Flow

Start of session

1. session_start()           → load context, read insights and warnings
2. Present brief to human    → "Last session: X. Insights: Y. Ready."
3. check() if task is complex → verify understanding before work

During work

4. remember() when you learn something   → auto-routes to right store
5. recall() when you need past context   → searches everything
6. check() before major decisions        → verify understanding

End of session

7. check() with corrections if any       → record what human corrected
8. session_end()                          → save journal + insights + consolidation
9. Done — all data saved locally (only push to git if user explicitly asks)

How Memory Compounds

Each layer feeds the next. The system gets better the more you use it.

SAVE: remember("JWT needs httpOnly cookies")
  → Auto-named: "lesson-jwt-httponly-cookies-security"
  → Indexed in palace + insights
  → Auto-linked to "architecture" room (keyword overlap)
  → Salience scored: recency(0.30) + access(0.25) + connections(0.20) + ...
RECALL: recall("cookie security") — 3 sessions later, different project
  → Finds the JWT insight via keyword match + graph edge traversal
  → Agent rates it useful → feedback boosts future ranking
  → Next recall on similar query → this result surfaces higher
COMPOUND: After 10 sessions
  → 200-line awareness contains cross-validated insights
  → watch_for warns about past mistakes before they repeat
  → Corrections auto-promote to awareness at 3+ occurrences
  → Graph connects related memories across rooms automatically

Best Practices

1. Call session_start at the beginning. Insights from past sessions prevent repeated mistakes. 2. Call session_end when done. If the session produced decisions, insights, or corrections, save them. 3. Insights should be reusable. Write them for a future agent who has never seen this project. 4. Match the human's language. If they write in Chinese, save in Chinese. 5. Don't over-save. 1-3 insights per session. 1-2 remember calls during work. More is noise. 6. Rate your recall results. Feedback makes future retrievals better. 7. Use check for ambiguous tasks. 5 seconds of verification beats 30 minutes of wrong work. 8. Read watch_for warnings. If session_start or check returns warnings, adjust your approach.

Storage

All data is local markdown + JSON at ~/.agent-recall/. No cloud, no telemetry, no API keys.

~/.agent-recall/
  awareness.md                              # 200-line compounding document (global)
  awareness-state.json                      # Structured awareness data
  awareness-archive.json                    # Demoted insights (preserved, not deleted)
  insights-index.json                       # Cross-project insight matching
  feedback-log.json                         # Retrieval quality ratings
  projects//
    journal/YYYY-MM-DD.md                   # Daily journals (legacy)
    journal/YYYY-MM-DD--arsave--NL--slug.md # Smart-named journals (auto-save)
    palace/rooms//                    # Persistent knowledge rooms
    palace/identity.md                      # Project intention + goals
    palace/graph.json                       # Memory connection edges
    alignment-log.json                      # Correction history for watch_for

Obsidian-compatible. Open palace/ as a vault to see the knowledge graph.

Platform Compatibility

| Platform | How to install | |----------|---------------| | Claude Code | claude mcp add --scope user agent-recall -- npx -y agent-recall-mcp | | Cursor | .cursor/mcp.json | | VS Code / Copilot | .vscode/mcp.json | | Windsurf | ~/.codeium/windsurf/mcp_config.json | | Codex | codex mcp add agent-recall -- npx -y agent-recall-mcp | | Hermes Agent | ~/.hermes/config.yaml under mcp_servers: | | Roo Code | .roo/mcp.json | | Claude Desktop | claude_desktop_config.json | | Gemini CLI | MCP server config | | OpenCode | MCP server config | | Any MCP client | command: npx, args: ["-y", "agent-recall-mcp"], transport: stdio |

All platforms use the same tools. No platform-specific behavior.

Security & Privacy

AgentRecall requires the MCP server to be running. If tool calls fail with "unknown tool", the human needs to install it first.

Installation (human runs once)

Claude Code:

claude mcp add --scope user agent-recall -- npx -y agent-recall-mcp

Cursor (.cursor/mcp.json):

{ "mcpServers": { "agent-recall": { "command": "npx", "args": ["-y", "agent-recall-mcp"] } } }

VS Code / GitHub Copilot (.vscode/mcp.json):

{ "servers": { "agent-recall": { "command": "npx", "args": ["-y", "agent-recall-mcp"] } } }

Windsurf (~/.codeium/windsurf/mcp_config.json):

{ "mcpServers": { "agent-recall": { "command": "npx", "args": ["-y", "agent-recall-mcp"] } } }

Codex:

codex mcp add agent-recall -- npx -y agent-recall-mcp

Hermes Agent (~/.hermes/config.yaml):

mcp_servers:
  agent-recall:
    command: npx
    args: ["-y", "agent-recall-mcp"]

Roo Code (.roo/mcp.json):

{ "mcpServers": { "agent-recall": { "command": "npx", "args": ["-y", "agent-recall-mcp"] } } }

Any MCP-compatible agent:

command: npx
args: ["-y", "agent-recall-mcp"]
transport: stdio

1. Call session_start at the beginning. Insights from past sessions prevent repeated mistakes. 2. Call session_end when done. If the session produced decisions, insights, or corrections, save them. 3. Insights should be reusable. Write them for a future agent who has never seen this project. 4. Match the human's language. If they write in Chinese, save in Chinese. 5. Don't over-save. 1-3 insights per session. 1-2 remember calls during work. More is noise. 6. Rate your recall results. Feedback makes future retrievals better. 7. Use check for ambiguous tasks. 5 seconds of verification beats 30 minutes of wrong work. 8. Read watch_for warnings. If session_start or check returns warnings, adjust your approach.