Agent Recall

AgentRecall v3.4.30 — Usage Guide

AgentRecall is a persistent memory system. Default surface: 5 tools (two verbs + three essentials). Full surface: 18 tools via npx agent-recall-mcp --full. This guide describes how and when to use them.

Two-verb model: session_start (inhale — load context) and session_end (exhale — save and compound). Everything else is available but secondary; most agents never need more than the default 5. See Automaticity Law below.

Setup

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

Visual setup guide (all 13 clients, copy-paste prompts): open warroom/install.html from the repo, or the GitHub raw link in a browser.

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's default surface provides 5 tools. Start the server with --full to enable the complete 18-tool surface.

Default tools (always available): session_start, session_end, remember, recall, check

Full-mode only (--full): memory_query, check_action, register_rule, pipeline_open, pipeline_close, pipeline_list, pipeline_current, pipeline_show, skill_write, skill_recall, skill_list, dashboard_export, session_end_reflect, project_board, project_status, digest, bootstrap_scan, bootstrap_import

Default tools

session_start

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

What it returns:

• project — detected project name
• identity — who the user is (1-2 lines)
• insights — top 5 awareness insights (title + confirmation count + severity)
• active_rooms — top 5 palace rooms by salience (with staleness flag + last_updated) (Palace = your project's long-term knowledge store, organized into topic rooms like "architecture", "goals", "blockers". Salience = relevance score 0-1 based on recency, access frequency, and connections. Rooms with stale=true haven't been updated in 7+ days.)
• cross_project — insights from other projects matching current context
• recent — today/yesterday journal briefs
• watch_for — predictive warnings from past correction patterns + decision calibration
• corrections — P0 behavioral rules (max 10, always loaded, never expire)
• resume — structured re-entry briefing: last_date, last_trajectory, sessions_count

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:

• Bug fix / lesson → knowledge store
• Architecture / decision → palace room
• Cross-project pattern → awareness system
• Session activity → journal

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:

• Writes daily journal entry
• Updates awareness with new insights (merge or add)
• Consolidates decisions/goals into palace rooms
• Archives demoted insights (preserved, not deleted)

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:

• 1-3 per session. Quality over quantity.
• Must be reusable. "Fixed a bug" is NOT an insight. "API returns null when session expires — always null-check auth responses" IS an insight.
• applies_when keywords determine when this insight surfaces in future sessions across ALL projects.

Return fields:

• journal_written — boolean, true if journal entry was saved
• awareness_updated — boolean, true if any insight was stored
• palace_consolidated — boolean, true if palace rooms were updated
• insights_processed — number of insights accepted
• quality_warnings — advisory warnings if insights are too short, lack evidence, or use event-verb phrasing (never blocks saves)
• card — formatted save summary (box-drawing card)
• merge_suggestions — array of similar recent entries (optional)

check

When: Before executing a complex task where you might misunderstand the human's intent. Also for tracking decision quality over time.

What it does:

• Records your understanding of the goal
• Returns watch_for — patterns from past corrections on this project
• Returns similar_past_deltas — times you misunderstood similar goals before
• After human responds, record the correction for future agents
• Optionally tracks decision trails with prior/posterior/evidence for calibrated judgment

Two-call pattern (correction tracking):

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.

Decision trail (Bayesian-inspired calibration):

For major decisions, track confidence and outcome to calibrate judgment over time:

check({
  goal: "Use GraphQL instead of REST",
  confidence: "medium",
  prior: 0.7,                    // initial confidence (0-1)
  evidence: [
    { factor: "Frontend needs flexible queries", direction: "supports", weight: 0.2 },
    { factor: "No GraphQL experience on team", direction: "weakens", weight: 0.3 }
  ],
  posterior: 0.55,               // updated confidence after evidence
  outcome: "rejected"            // final result: "confirmed", "rejected", "partial", or free text
})

When outcome is provided, the decision trail is persisted to the palace decisions room. After 3+ closed decisions, session_start surfaces calibration warnings: "Your priors average 0.8 but outcomes average 0.5 — you're overconfident."

Returns: recorded, watch_for, similar_past_deltas, decision_id (when outcome provided), decision_trail_saved, calibration_note

Full-mode tools (npx agent-recall-mcp --full)

These tools are available when the server is started with --full. Most agents never need them — the default 5 tools carry all compounding memory value. Enable --full for project narrative tracking (pipeline), procedural rules (skills), status dashboards, context caching, or first-time bootstrap.

project_board

When: Start of a new session when you don't know which project to work on.

What it does: Scans all projects and returns a status board — last activity date, pending work, active blockers. Use this before session_start to pick which project to load.

project_board()

project_status

When: Quick check on a specific project's health without loading full context.

What it returns: Last trajectory, active blockers, palace room freshness (stale flag), next steps, summary line. Lighter than session_start — no awareness or cross-project loading.

project_status({ project: "auto" })