agent-recall-mcp

Give your AI agent a brain that survives every session.

MCP server for persistent agent memory — session journals, structured JSON state,
Think-Execute-Reflect quality loops, cache-aware cold start, and alignment detection.
Works with Claude Code, Cursor, VS Code Copilot, Windsurf, Claude Desktop, and any MCP client.

Zero cloud. Zero telemetry. All data stays on your machine.

Why AgentRecall?

Quick Start

Claude Code

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

Cursor

.cursor/mcp.json:

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

VS Code / Windsurf / Claude Desktop

Same pattern — add npx -y agent-recall-mcp as an MCP server command.

12 Tools

Session Memory (6 tools)

v3 Architecture (3 tools) — NEW in v2.1.1

Alignment & Synthesis (3 tools)

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    Agent Session                             │
│                                                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐  │
│  │ L1: Working   │  │ L2: Journal  │  │ L3: Synthesis    │  │
│  │ Memory        │  │ (daily)      │  │ (cross-session)  │  │
│  │ ~50 tokens    │  │ ~800 tokens  │  │ ~200 tokens      │  │
│  │               │  │              │  │                  │  │
│  │ journal_      │  │ journal_     │  │ context_         │  │
│  │ capture       │  │ write/read   │  │ synthesize       │  │
│  └──────┬───────┘  └──────┬───────┘  └────────┬─────────┘  │
│         │ synthesized      │ synthesized        │            │
│         └────────►─────────┘────────►───────────┘            │
│                                                             │
│  ┌──────────────────────────────────────────────────────┐   │
│  │ v3: JSON State Layer (agent-to-agent, no prose)      │   │
│  │ journal_state → .state.json alongside .md            │   │
│  └──────────────────────────────────────────────────────┘   │
│                                                             │
│  ┌──────────────────────────────────────────────────────┐   │
│  │ v3: Cache Layer (hot/warm/cold)                      │   │
│  │ journal_cold_start → loads 3 files, not 28           │   │
│  └──────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

Cache-Aware Cold Start (v3)

┌─ HOT (0-1 day) ─────────────────────────────────┐
│ Full JSON state + brief from markdown            │
│ → Everything the next agent needs                │
└──────────────────────────────────────────────────┘
         ↓
┌─ WARM (2-7 days) ────────────────────────────────┐
│ Brief summary only (first 2KB of journal)        │
│ → "What happened this week" context              │
└──────────────────────────────────────────────────┘
         ↓
┌─ COLD (7+ days) ─────────────────────────────────┐
│ Count only. Use journal_read for full content.   │
│ Use journal_archive to move to archive/ folder.  │
└──────────────────────────────────────────────────┘

JSON State (v3) — Agent-to-Agent Format

{
  "version": "2.1.1",
  "date": "2026-04-07",
  "project": "my-project",
  "completed": [
    { "task": "built dashboard", "result": "11 pages, 35 tabs" }
  ],
  "failures": [
    { "task": "extraction", "what_went_wrong": "missed sub-tabs", "root_cause": "context fatigue", "fixed": true }
  ],
  "state": {
    "genome": { "status": "v3.2", "details": "8 dimensions" }
  },
  "next_actions": [
    { "priority": "P0", "task": "verify against real site" }
  ],
  "insights": [
    { "claim": "extraction quality = replication quality", "confidence": "high", "evidence": "4 sites tested" }
  ],
  "counts": { "pages": 91, "tabs": 35, "api_routes": 3 }
}

The next agent reads this in milliseconds. No prose parsing. No ambiguity.

Storage

~/.agent-recall/
└── projects/
    └── {project}/
        └── journal/
            ├── index.md                  ← auto-generated
            ├── 2026-04-07.md             ← L2: daily journal (markdown)
            ├── 2026-04-07.state.json     ← v3: structured state (JSON)
            ├── 2026-04-07-log.md         ← L1: raw Q&A capture
            ├── 2026-04-07-alignment.md   ← alignment checks
            └── archive/                  ← v3: cold storage
                ├── index.md              ← one-line summaries
                └── 2026-03-25.md         ← archived entries

Think-Execute-Reflect Loop

Every session follows a structured quality cycle:

🧠 THINK    → Was the approach right? Was research done?
⚡ EXECUTE  → What happened vs what was planned? (use COUNTS, not feelings)
🔍 REFLECT  → 5-dimension quality score + Intelligent Distance gap analysis
🔄 FEEDBACK → Loop (needs iteration) or Exit (quality sufficient)

New in v2.1.1: The Execute section requires COUNTS:

"Built 11 pages, 35 tabs, verified 82/91 routes return 200" — not "went well"

New in v2.1.1: Failures section records what was ATTEMPTED and FAILED:

Not just successes. Failures are more valuable for learning.

Environment Variables

CLI

npx agent-recall-mcp              # Start MCP server (stdio)
npx agent-recall-mcp --help       # Show help
npx agent-recall-mcp --list-tools # List all 12 tools as JSON

Feedback & Contributing

Built by tongwu at NovadaLabs.

We'd love your feedback. If you're using AgentRecall, tell us what works and what doesn't:

• Email: tongwu0824@gmail.com
• GitHub Issues: NovadaLabs/AgentRecall

License

MIT

agent-recall-mcp（中文文档）

给你的 AI 智能体一个跨会话记忆的大脑。

MCP 服务器 — 双层会话记忆 + v3 JSON 状态层 + 缓存感知冷启动 + Think-Execute-Reflect 质量循环。兼容所有 MCP 客户端。

零云端。零遥测。所有数据保存在本地。

快速开始

# Claude Code
claude mcp add agent-recall -- npx -y agent-recall-mcp

# Cursor: .cursor/mcp.json
{ "mcpServers": { "agent-recall": { "command": "npx", "args": ["-y", "agent-recall-mcp"] } } }

12 个工具

会话记忆（6 个）

v3 架构（3 个）— v2.1.1 新增

对齐 & 合成（3 个）

核心理念

记忆解决遗忘，AgentRecall 解决误解。

人类和 AI 之间的理解差距是结构性的 — 人类说话前后矛盾、碎片化、含糊不清；AI 则以完美的自信构建错误的东西。AgentRecall 通过对齐检测、矛盾提醒和跨会话合成来弥合这个「智能距离」。

许可证

MIT — tongwu @ NovadaLabs

反馈邮箱：tongwu0824@gmail.com