MCP Server

Active

MIT

io.github.Goldentrii/agent-recall MCP Server

io.github.Goldentrii/agent-recall

Correction-first agent memory that learns how you think, with precision KPI tracking and 5 cognitive layers—local-only by default.

Repository Registry

What is the io.github.Goldentrii/agent-recall MCP server?

AgentRecall is an MCP server that provides persistent, compounding agent memory organized into 5 cognitive layers (episodic, semantic, procedural, narrative, correction). It automatically captures corrections and tracks a precision KPI to measure whether agents actually heed warnings, storing everything locally in markdown under ~/.agent-recall/ with optional semantic search via OpenAI embeddings.

AgentRecall turns corrections into learning. Every time you correct your agent, that correction is stored, weighted, and recalled in future sessions. After multiple sessions, your agent doesn't just remember your project—it understands how you think. The system uses FSRS-lite spaced repetition decay and keyword+RRF retrieval (fully local by default), with optional vector search. It's designed around the principle that memory only compounds if used automatically, not on demand.

How to install io.github.Goldentrii/agent-recall

Copy-paste configuration for popular MCP clients.

transport: stdio

Config generated by PluginBench — verify against the source before use.

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json

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

Cursor

~/.cursor/mcp.json

{
  "mcpServers": {
    "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"
      ]
    }
  }
}

VS Code

.vscode/mcp.json

{
  "servers": {
    "agent-recall": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "agent-recall-mcp"
      ]
    }
  }
}

Claude Code

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

Tools & capabilities

Tools this server exposes to the agent.

session_start — Load deep context at the beginning of a session: palace rooms, corrections, task-specific recall.
session_end — Write journal entries, consolidate palace knowledge, compound awareness insights, and perform semantic prefetch at the end of a session.
remember — Capture corrections and other memory records with type, severity, holder, and evidence for behavioral calibration.
arstatus — Display status board across all projects: pending work, blockers, and relevance scores to orient the agent.
arbootstrap — Scan your machine for existing projects and import them into AgentRecall.

Use cases

Prevent repeated mistakes by automatically surfacing past corrections when the same issue recurs
Build a searchable knowledge base of your project architecture, goals, and blockers organized into semantic rooms
Track agent behavior calibration with precision KPI (heeded/retrieved) to identify high-signal vs. noisy warnings
Consolidate multi-session work into journal entries, narrative phases, and cross-project insights
Maintain an offline-first memory system in local markdown that integrates with Obsidian, git, and grep

io.github.Goldentrii/agent-recall MCP server FAQ

What is AgentRecall?

AgentRecall is an MCP server that creates a learning loop for AI agents. It captures corrections, stores them in 5 cognitive memory layers, and automatically recalls relevant warnings in future sessions. The core innovation is a precision KPI that tracks whether the agent actually heeds warnings—if precision drops below 0.3, that warning stops being injected as noise.

Is AgentRecall free?

Yes, AgentRecall is MIT-licensed and open source. It runs entirely locally on your machine by default. Optional semantic vector search requires an OpenAI API key, but the default keyword+RRF retrieval is fully local with zero cloud dependency.

How do I install it in Claude Code or Cursor?

For Claude Code: `claude mcp add --scope user agent-recall -- npx -y agent-recall-mcp`. For Cursor, add to `.cursor/mcp.json`: `{ "mcpServers": { "agent-recall": { "command": "npx", "args": ["-y", "agent-recall-mcp"] } } }`. For other editors, use the generic MCP JSON format.

Do I need authentication or API keys?

No authentication is required to use AgentRecall locally. All memory is stored in `~/.agent-recall/` as markdown files. Optional semantic vector search requires `OPENAI_API_KEY`, but leaving it unset keeps everything local with zero cloud calls.

What are the 5 memory layers?

Episodic (session journal), Semantic (topic-clustered facts with wikilinks), Procedural (IF-THEN rules), Narrative (project phases and synthesis), and Correction (behavioral rules with precision KPIs). All are stored as local markdown under `~/.agent-recall/projects/`.

How does the precision KPI work?

Each correction tracks `precision = heeded / retrieved`—of the times AgentRecall surfaced a warning, how often did the agent act on it? Corrections with precision < 0.3 are archived as noise; those ≥ 0.8 are promoted faster as high-signal insights.

README (reference)

Source of truth, from the repository.

English · 中文

<h1 align="center">AgentRecall</h1> Your agent doesn't just remember. It learns how you think. Every correction saved is a mistake never repeated. Every insight compounded is tokens never wasted rebuilding context. Persistent, compounding memory + automatic correction capture. MCP server + SDK + CLI. <a href="https://t.me/+ywZwoHrg3AM0NDVi"><img src="https://img.shields.io/badge/Telegram-Community-2CA5E0?style=flat-square&logo=telegram" alt="Telegram Community"></a> <a href="https://www.npmjs.com/package/agent-recall-mcp"><img src="https://img.shields.io/npm/v/agent-recall-mcp?style=flat-square&label=MCP&color=5D34F2" alt="MCP npm"></a> <a href="https://www.npmjs.com/package/agent-recall-sdk"><img src="https://img.shields.io/npm/v/agent-recall-sdk?style=flat-square&label=SDK&color=0EA5E9" alt="SDK npm"></a> <a href="https://www.npmjs.com/package/agent-recall-cli"><img src="https://img.shields.io/npm/v/agent-recall-cli?style=flat-square&label=CLI&color=10B981" alt="CLI npm"></a> <a href="https://github.com/Goldentrii/AgentRecall/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-brightgreen?style=flat-square" alt="License"></a> <img src="https://img.shields.io/badge/MCP-5_tools_default-orange?style=flat-square" alt="Tools"> <img src="https://img.shields.io/badge/memory_layers-5-7C3AED?style=flat-square" alt="5 layers"> <img src="https://img.shields.io/badge/cloud-zero_by_default-blue?style=flat-square" alt="Zero cloud by default"> <img src="https://img.shields.io/badge/decay-FSRS--lite-3B82F6?style=flat-square" alt="FSRS-lite decay"> <img src="https://img.shields.io/badge/retrieval-keyword_%2B_RRF-8B5CF6?style=flat-square" alt="Keyword + RRF retrieval"> <img src="https://img.shields.io/badge/feedback-precision_KPI-F59E0B?style=flat-square" alt="Precision KPI"> <a href="#the-session-loop"><img src="https://img.shields.io/badge/%2Farstatus-START_HERE-22C55E?style=for-the-badge" alt="/arstatus"></a> <a href="#the-session-loop"><img src="https://img.shields.io/badge/%2Farstart-Load_Context-4ECDC4?style=for-the-badge" alt="/arstart"></a> <a href="#the-session-loop"><img src="https://img.shields.io/badge/%2Farsave-Save_Session-FF6B6B?style=for-the-badge" alt="/arsave"></a> <a href="#the-session-loop"><img src="https://img.shields.io/badge/%2Farsaveall-Batch_Save-FFD93D?style=for-the-badge" alt="/arsaveall"></a> <a href="#the-session-loop"><img src="https://img.shields.io/badge/%2Farbootstrap-Transfer_Memory-8B5CF6?style=for-the-badge" alt="/arbootstrap"></a> <details> <summary>🤖 Agent found this repo? Install AgentRecall for your human (click to expand)</summary>

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.

</details>

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?

Feature	AgentRecall	Mem0	Zep	Letta
Correction tracking + precision KPI	✅ Core feature	❌	❌	❌
Behavioral calibration across sessions	✅	❌	❌	Partial
Local markdown, zero cloud by default	✅ (vector search optional, opt-in)	❌ cloud	❌ cloud	❌ cloud
MCP native	✅	✅	✅	✅
FSRS-lite decay + keyword/RRF retrieval	✅	❌	❌	❌
Free / open source	✅ MIT	Freemium	Freemium	Apache
Works offline	✅ (default; vector search needs network)	❌	❌	Partial

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:

Layer	Type	What it holds	Path
1	Episodic	What happened in each session, chronologically. Auto-written during work.	`journal/`
2	Semantic	Topic-clustered facts with `[[wikilinks]]`: Architecture, Goals, Blockers.	`palace/rooms/`
3	Procedural	IF-THEN production rules — reusable how-tos.	`palace/skills/`
4	Narrative	Project phases: Goal → What was hard → How solved → Synthesis.	`palace/pipeline/`
5	Correction	Behavioral calibration: rules the agent must follow, with precision KPIs.	`corrections/`
+	Awareness	Cross-project insights promoted from N-confirmed corrections — the compounding layer.	`palace/awareness`

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

Command	When	What it does
🔴 `/arstatus`	First — every session	Status board across ALL projects: pending work, blockers, relevance scores. Pick by number.
`/arstart`	After picking a project	Load deep context: palace rooms, corrections, task-specific recall.
🔴 `/arsave`	Last — every session	Write journal + palace consolidation + awareness compounding + semantic prefetch.
`/arsaveall`	End of day (multi-session)	Batch save all parallel sessions — scan, merge, deduplicate, done.
`/arbootstrap`	First install / migrating	Scan your machine for existing projects and import them.

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.

What it does	Result
Mine patterns across all projects	Repeated corrections promote to `palace/awareness`
Ebbinghaus salience decay	Low-signal rooms fade; your palace stays sharp
Journal rollups	Entries >30 days compress into summary rooms
Awareness graduation	Corrections confirmed N× times go cross-project
Telegram report	Nightly summary: learned · decayed · crystallized

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.

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

cd warroom
python3 -m http.server 8080

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

Platform	Mechanism	Status
Claude Code	MCP server + skill + hooks	✅ Primary
Cursor · Windsurf · VS Code (Copilot) · Codex	MCP server	✅
Any JS/TS app	SDK (`agent-recall-sdk`)	✅
Terminal / CI	CLI (`ar`)	✅

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.

Related MCP servers

io.github.Goldentrii/proxy-veil

Maintained

Residential proxy MCP server for AI agents — geo-targeting, sticky sessions, anti-bot bypass.

JavaScript

View repository →