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:

• 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

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" })

bootstrap_scan

When: First time using AgentRecall, or when /arstatus shows an empty board.

What it does: Scans your machine for existing projects — git repos, Claude AutoMemory (~/.claude/projects/), and CLAUDE.md files. Returns a structured report of what CAN be imported. Read-only, no writes.

What it scans:

• ~/Projects/, ~/work/, ~/code/, ~/dev/, ~/src/, ~/repos/, ~/github/ for git repos
• ~/.claude/projects/ for Claude AutoMemory (user profile, project memories, feedback)
• CLAUDE.md files in project roots

How to use:

bootstrap_scan()

Returns: projects (array of discovered projects with importable items), global_items (user profile), stats (totals + scan duration)

bootstrap_import

When: After reviewing bootstrap_scan results, to import selected projects.

What it does: Creates AgentRecall entries for discovered projects — palace rooms, identity.md, knowledge entries from Claude memory, initial journal from git history.

How to use:

bootstrap_import({
  scan_result: "<JSON from bootstrap_scan>",
  project_slugs: ["my-app", "api-server"],    // optional: import only these
  item_types: ["identity", "architecture"]     // optional: import only these types
})

CLI equivalent:

ar bootstrap                    # scan and show what's available
ar bootstrap --dry-run          # preview what would be imported
ar bootstrap --import           # import all new projects
ar bootstrap --import --project my-app  # import one project

What gets imported per project:

• identity — palace identity.md from project name + description + language
• memory — Claude AutoMemory .md files → palace knowledge room
• architecture — CLAUDE.md content → palace architecture room
• trajectory — git log → initial journal entry with recent activity

Safety:

• Scan is read-only — never writes to your machine or to AgentRecall
• Import only writes to ~/.agent-recall/, never modifies source files
• Skips .env, credentials, .pem, .key files — never reads secrets
• Projects already in AgentRecall are skipped (no double-import)

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
                                           (stores: journal for daily activity, palace rooms for persistent decisions, awareness for cross-project insights)
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.
9. Run bootstrap on first install. If /arstatus shows no projects, bootstrap_scan discovers what's already on your machine and imports it in seconds.
10. Check active_rooms in session_start. Palace rooms with high salience contain your project's most important decisions and patterns. Rooms marked stale may need updating.

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/<name>/
    journal/YYYY-MM-DD.md                   # Daily journals (legacy)
    journal/YYYY-MM-DD--arsave--NL--slug.md # Smart-named journals (auto-save)
    palace/rooms/<room>/                    # Persistent knowledge rooms
    palace/rooms/decisions/                 # Decision trail records (prior/posterior/outcome)
    palace/identity.md                      # Project intention + goals
    palace/graph.json                       # Memory connection edges
    alignment-log.json                      # Correction history for watch_for
    digest/                                 # Pre-digested context summaries

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

• Zero network: No outbound HTTP requests, no telemetry, no analytics, no cloud sync. All operations are local filesystem reads/writes.
• Zero credentials: No API keys, tokens, or environment variables required.
• Scoped filesystem access: Reads/writes only to ~/.agent-recall/ (configurable via --root flag). Does not access files outside this directory unless the agent explicitly passes project-specific paths.
• No code execution: The MCP server does not execute arbitrary code, run shell commands, or spawn child processes.
• Transparent storage: All data is human-readable markdown and JSON. Inspect it anytime: ls ~/.agent-recall/ or open it as an Obsidian vault.
• Open source: Full source at github.com/Goldentrii/AgentRecall. MIT license.

Safety guarantees:

• Scan is read-only — never writes to your machine
• Import only writes to ~/.agent-recall/ — never modifies source files
• Skips .env, credentials, .pem, .key — never reads secrets
• Projects already in AgentRecall are skipped (no double-import)

For MCP-only environments (Codex, Cursor, VS Code Copilot):

bootstrap_scan()                    # discover what's on the machine
bootstrap_import({ scan_result })   # import selected projects

For CLI:

ar bootstrap                        # scan and show results
ar bootstrap --dry-run              # preview what would be imported
ar bootstrap --import               # import all new projects
ar bootstrap --import --project X   # import one project

After bootstrap, run /arstatus — your projects are ready.

/arstatus, /arsave, /arstart, /arsaveall, and /arbootstrap

[!TIP] New to AgentRecall? Read the → Command Reference — full instructions, all example outputs, installation, and troubleshooting in one place.

[!IMPORTANT] Run /arstatus at the start of every session. It shows all your projects, what's pending, what's blocked, and lets you pick what to work on — by number, not by remembering project names. Without it, a fresh agent has no idea where to begin.

| Command | When | What it does | |---------|------|-------------| | ⭐ /arstatus | Every session — run this first | Status board across ALL projects: pending work, blockers, numbered pick list. The true cold start. | | /arstart | After picking a project | Load deep context for one project: palace rooms, corrections, task-specific recall | | /arsave | End of session | Write journal + consolidate to palace + update awareness | | /arsaveall | End of day (multi-session) | Batch save all parallel sessions at once — scan, merge, deduplicate, done | | /arbootstrap | First install / switching from another memory system | Scan your machine for existing projects and import them into AgentRecall in seconds |

The session flow: /arstatus → pick a number → /arstart <project> → work → /arsave.

Running 5 agents in parallel? Don't /arsave five times. Type /arsaveall once — it scans all of today's sessions across all projects, merges them into consolidated journals, deduplicates insights, and updates awareness in one shot. Each session writes to its own file (session-ID scoped), so no conflicts, no data loss, no matter how many windows you have open.

What You'll See

Type /arstatus → see everything in flight across all projects, pick by number:

──────────────────────────────────────────────────────────────
  AgentRecall  Status Board        2026-04-21    5 projects
──────────────────────────────────────────────────────────────

  1  ⚠ novada-site       2026-04-21   BLOCKED
       Blocked: .env.local missing — Phase 1 cannot proceed

  2  ● novada-mcp        2026-04-21
       Next: fix novada_search POST /request → publish v0.8.0

  3  ● prismma-scraper   2026-04-17
       Next: UI upgrade Option A — light mode + 3D visuals

  4  ✓ AgentRecall       2026-04-21   complete
       Collecting real production data

──────────────────────────────────────────────────────────────
  Enter a number, or:
    N  New project (with memory — agent knows your full history)
    X  New project (clean slate — no prior context, pure objectivity)
──────────────────────────────────────────────────────────────

Type /arsave → the system saves everything and renders a card with exact file paths and counts:

──────────────────────────────────────────────────────────────