AgentRecall — The Intelligent Distance Protocol

Minimize information loss between human and AI — across every session, every agent, every project. Not a memory tool. A communication protocol. The gap between human and AI cognition is structural — AgentRecall designs around it.

The Problem

The obvious problem: AI agents forget everything between sessions. Cold-start amnesia costs 2,000–5,000 tokens per session.

The real problem: Humans and AI misunderstand each other — structurally, repeatedly, expensively. Humans contradict themselves, communicate in fragments, say "make it better" when they mean 10 different things. AI interprets literally and builds the wrong thing with perfect confidence.

Memory solves forgetting. AgentRecall solves misunderstanding.

Three Pillars

Pillar	What	Why
Goal Alignment	Agents have full freedom in HOW. Protocol ensures WHAT.	Don't prescribe methods — clarify the destination.
Structured Memory	L1 (working) → L2 (episodic) → L3 (semantic synthesis)	Writing journals isn't enough. Agents must synthesize and detect contradictions.
Misunderstanding Detection	Confidence checks, nudge on human inconsistency, feedback loop	Most protocols prevent misunderstanding. This one also detects it.

Read the full protocol spec →

Quick Start

MCP Server (any agent)

# 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 — .vscode/mcp.json
{ "servers": { "agent-recall": { "command": "npx", "args": ["-y", "agent-recall-mcp"] } } }

Skill (Claude Code)

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

Say "save" to journal. Say "read the latest journal" to resume.

9 MCP Tools

Tool	Purpose
`journal_read`	Read entry by date or "latest". Filter by section.
`journal_write`	Write or update journal content
`journal_capture`	Lightweight L1 Q&A capture
`journal_list`	List recent entries
`journal_search`	Full-text search across history
`journal_projects`	List all tracked projects
`alignment_check`	Record confidence + understanding + human corrections
`nudge`	Surface contradiction between current and past input
`context_synthesize`	L3 synthesis: patterns, contradictions, goal evolution

How Alignment Detection Works

When an agent isn't sure it understands:

ALIGNMENT CHECK:
- Goal: Build a REST API for user management
- Confidence: medium
- Assumptions: PostgreSQL, no auth yet, CRUD only
- Unclear: Should this include role-based access?

Human confirms or corrects. The delta is logged. Over time, patterns reveal where misunderstanding is most likely.

How Nudge Protocol Works

When the agent detects the human contradicts a prior decision:

NUDGE:
- You decided Clerk for auth on March 25.
- Now you're asking for custom auth from scratch.
- Has the goal changed, or should we stick with Clerk?

Not the agent being difficult — it's helping the human clarify their own thinking.

Three-Layer Memory

L1: Working Memory    [per-turn, ~50 tokens]    "What happened"
    ↓ synthesized into
L2: Episodic Memory   [daily journal, ~800 tok]  "What it means"
    ↓ synthesized into
L3: Semantic Memory   [cross-session, ~200 tok]  "What's true across sessions"
    (contradiction detection + goal evolution tracking)

Supported Agents

Agent	Skill	MCP	Protocol
Claude Code	✅	✅	✅
Cursor	⚡	✅	✅
VS Code Copilot	—	✅	✅
Windsurf	⚡	✅	✅
Claude Desktop	—	✅	✅
Any MCP agent	—	✅	✅
Any AI agent	—	—	✅ (manual)

Real Results

Validated over 20+ sessions across production projects:

Cold-start: 5 min → 2 seconds
Decision history: 0% → 100% retained
Misunderstanding caught before wrong work: 4 instances in first week
Quality loop caught 4 code review gaps that would have shipped

Contributing

Use the protocol for a week → report
Implement it in a new agent → PR welcome
Improve the spec → protocol doc

License

MIT — Concept & Design: Tongwu

agent-recall-mcp

Quick Install