AgentRecall MCP Server

English · 中文

1. Install the MCP server (Claude Code):

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

Generic MCP JSON for other clients:

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

2. First message of every new session, run the loop:

At the start of a session, call session_start to load context.
When the human corrects you, call remember with type "correction".
At the end of a session, call session_end to compound what you learned.

---

What & Why

AgentRecall is not a memory tool. It's a learning loop. Memory is the mechanism; understanding is the goal. Every time you correct your agent — "no, not that version", "put this section first", "ask me before you assume" — that correction is stored, weighted, and recalled next time. After 10 sessions your agent doesn't just remember your project; it understands how you think.

• Correction-first. When you say "no, that's wrong", we log a CorrectionRecord with severity, holder, and evidence. After N confirmations across sessions it auto-promotes to a cross-project insight.
• Measurable learning loop. Every correction tracks retrieved_count, heeded_count, recurrence_count, precision. The KPI that matters: did the same bug recur after we warned about it?
• Five memory types. Episodic, semantic, procedural, narrative, correction — mapped to the canonical cognitive-psychology taxonomy (Squire 2004, Tulving 1972).
• Local markdown, local by default. Everything lives in ~/.agent-recall/. Open it in Obsidian, grep it in the terminal, version it in git. The default keyword + RRF retrieval is fully local — zero cloud, no API keys, no lock-in. Semantic vector search is optional: set OPENAI_API_KEY and query/content text is sent to OpenAI for embeddings. Leave it unset and nothing leaves your machine.
• Backed by published math. FSRS-lite decay (Ebbinghaus → SuperMemo → FSRS-6), RRF fusion (Cormack 2009). A Modern Hopfield re-rank primitive (Ramsauer 2020) ships in the codebase but is not wired into the default retrieval path — what runs today is BM25/keyword + RRF, plus optional vector search.

The Automaticity Law. Memory only compounds if it's used automatically, not on demand. Measured on the live corpus: push channels (session_start, session_end, correction hooks) show repeated behavior-changing usage, while pull channels had zero organic calls across 44 projects over weeks of real use — including from the agent that built them. That's why only 5 tools ship by default; the two-verb model (inhale/exhale) carries all the compounding value, and everything else is opt-in via --full.

Injection Precision KPI. Every correction tracks precision = heeded / retrieved — of the times we surfaced this warning, how often did the agent actually act on it? precision < 0.3 → archive candidate (noise we should stop injecting). precision ≥ 0.8 → promote faster (high-signal, compound it sooner). This is the measurability claim: a memory system you can prove is working.

---

Why AgentRecall vs X?

The difference: AgentRecall is the only system that tracks whether the agent actually acted on a warning — not just that it stored one.

---

Quick Start

Visual setup guide — all 13 clients, copy-paste prompts: open warroom/install.html from the repo (or after unzipping the War Room release) in any browser. No server needed.

MCP Server — for AI agents

# 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 — .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

Skill (Claude Code only):

mkdir -p ~/.claude/skills/agent-recall
curl -o ~/.claude/skills/agent-recall/SKILL.md \
  https://raw.githubusercontent.com/Goldentrii/AgentRecall/main/SKILL.md

SDK & CLI

npm install agent-recall-sdk        # JS/TS apps
npx agent-recall-cli recall "topic" # terminal & CI

import { AgentRecall } from "agent-recall-sdk";
const memory = new AgentRecall({ project: "my-app" });
await memory.capture("What stack?", "Next.js + Postgres");
const ctx = await memory.recall("rate limiting");

---

5 Memory Layers

The canonical cognitive-psychology taxonomy mapped to your agent's filesystem:

All layers share one canonical naming grammar (<scope>/<type>/[<topic>/]<temporal>--<slug>.md) so any agent can compose retrieval paths from intent. Existing files keep working via a legacy_path view — no migration needed.

---

The Session Loop

Without /arstatus, a fresh agent has zero orientation. Without /arsave, nothing compounds. These two are the entire loop.

---

🌙 Dreaming — Nightly Consolidation (optional)

An autonomous overnight agent that runs while you sleep and compounds everything your sessions wrote during the day.

Requires a live Claude Code login. If the session expires, dream skips with a Telegram alert.

# Fix expired login (run this when dreaming stops)
claude login

Dream reports are saved locally to ~/.agent-recall/dreams/YYYY-MM-DD.md.

---

🖥️ War Room Dashboard — Download & Deploy

A local-first visual dashboard for your memory: an activity calendar, per-project status, corrections, and insights — all rendered from your local ~/.agent-recall/ data. Fully offline (vendored assets), no Node and no build step.

1. Download ar-warroom-v3.4.32.zip from the latest GitHub Release.
2. Unzip it, then serve it locally:

cd warroom
python3 -m http.server 8080

1. Open http://localhost:8080/AgentRecall.html

This is the recommended onboarding for Hermes / OpenClaw / OpenCode users too — one offline page to see everything your agent has learned.

---

Architecture

TypeScript monorepo, 4 published packages: core (storage + tool logic), mcp-server (thin MCP wrappers), sdk (programmatic API), cli (the ar command). All memory is local markdown under ~/.agent-recall/projects/<slug>/ — journal/, corrections/, and palace/ (rooms, skills, pipeline, awareness). An optional Supabase mirror adds pgvector semantic recall; all-local stays the default.

Platform Compatibility

---

Links

• Full reference → README.full.md
• Docs → docs/ — command reference, architecture deep-dives
• Changelog → UPDATE-LOG.md — phase-by-phase evolution + design reasoning
• Benchmark report → REPORT-2026-05-30.html — Phase 6 visual report
• Skill → SKILL.md — Claude Code skill definition
• Community → Telegram · GitHub Issues

Contributing

PRs welcome. Open an issue first for anything substantive — the design is opinionated and grounded in published research; we want changes grounded the same way.

License

MIT — see LICENSE.