AgentRecall X MCP Server

English · 中文

<p align="center"> <picture> <source media="(max-width: 600px) and (prefers-color-scheme: dark)" srcset="assets/readme/hero-narrow-dark.svg"> <source media="(max-width: 600px)" srcset="assets/readme/hero-narrow-light.svg"> <source media="(prefers-color-scheme: dark)" srcset="assets/readme/hero-dark.svg"> <img src="assets/readme/hero-light.svg" alt="AgentRecall: teach one agent, every agent remembers. Claude Code, Codex, Cursor, claude.ai and any MCP client connect to one memory, and at session_start each agent receives the same cards: HARD RULES, project state and the owner card."> </picture> </p> <p align="center"> The rules you set, the corrections you make and the state of your project, handed to every agent at the start of every session. Hosted for free, or offline on your disk. </p> <p align="center"> <a href="https://agentrecallx.com"><img src="assets/readme/site-home.jpg" alt="The AgentRecall home page at agentrecallx.com: a gold tree and a cyan tower with the headline 'Two kinds of intelligence', and the Connect an agent and Run it locally buttons." width="100%"></a> </p> <p align="center"> <strong>Try it now: <a href="https://agentrecallx.com">agentrecallx.com</a></strong> Connect any MCP agent with one URL, sign in with GitHub, free.<br> For agents: instructions at <a href="https://agentrecallx.com/connect.md">https://agentrecallx.com/connect.md</a>. </p> <p align="center"> <a href="https://agentrecallx.com/healthz"><img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fagentrecallx.com%2Fhealthz&query=%24.version&label=hosted&prefix=v&suffix=%20live&color=2E9E6A&style=flat-square" alt="Hosted server status"></a> <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-X/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/Goldentrii/AgentRecall-X/ci.yml?branch=main&style=flat-square&label=CI%20ubuntu%2Bwindows" alt="CI"></a> <a href="https://github.com/Goldentrii/AgentRecall-X/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-brightgreen?style=flat-square" alt="License"></a> <a href="https://mcpvault.io/servers/agentrecall-x/health?utm_source=external_badge&amp;utm_medium=referral&amp;utm_campaign=mcp_health_report"><img src="https://mcpvault.io/badge/agentrecall-x.svg" alt="MCPVault: claimed"></a> <br> <img src="https://img.shields.io/badge/storage-local_markdown-blue?style=flat-square" alt="Local markdown"> <img src="https://img.shields.io/badge/fusion-RRF_k%3D60-8B5CF6?style=flat-square" alt="RRF k=60"> <img src="https://img.shields.io/badge/forgetting-e%5E(%E2%88%92t%2FS)-7C3AED?style=flat-square" alt="Forgetting curve"> <img src="https://img.shields.io/badge/every_constant-labelled-orange?style=flat-square" alt="Every constant labelled"> </p> <p align="center"> <a href="#the-session-loop"><img src="https://img.shields.io/badge/%2Farstart-OPEN·START_HERE-22C55E?style=for-the-badge" alt="/arstart"></a> <a href="#the-session-loop"><img src="https://img.shields.io/badge/%2Farsave-SAVE-FF6B6B?style=for-the-badge" alt="/arsave"></a> <a href="#the-session-loop"><img src="https://img.shields.io/badge/%2Farrecall-SEARCH-4ECDC4?style=for-the-badge" alt="/arrecall"></a> <a href="#the-session-loop"><img src="https://img.shields.io/badge/%2Farreflect-CONSOLIDATE-8B5CF6?style=for-the-badge" alt="/arreflect"></a> </p> <p align="center"> <a href="https://agentrecallx.com/connect"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/readme/door-hosted-dark.svg"><img src="assets/readme/door-hosted-light.svg" width="400" alt="Hosted: sign in with GitHub at agentrecallx.com. One URL for any MCP agent, ready in about a minute. Connect an agent."></picture></a> <a href="https://agentrecallx.com/local"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/readme/door-local-dark.svg"><img src="assets/readme/door-local-light.svg" width="400" alt="Local: fully offline on your own machine with plain markdown. The MCP server installs with one npx command; optional hooks automate the loop. Install locally."></picture></a> </p> <p align="center"><a href="#hosted-connect-your-agent">Hosted setup in this README</a> · <a href="#local-install">Local install in this README</a></p>

Hosted: connect your agent

One server URL for every agent: https://agentrecallx.com/mcp. Add it, sign in with GitHub when the browser opens, and every agent you connect shares the same memory. Sign-up is open to any GitHub account and free.

Claude Code

claude mcp add --scope user --transport http agent-recall https://agentrecallx.com/mcp

Then type /mcp inside Claude Code, pick agent-recall and choose Authenticate.

Codex

codex mcp add agent-recall --url https://agentrecallx.com/mcp

Codex opens the sign-in page itself. If you closed it, run codex mcp login agent-recall.

Cursor: add this to ~/.cursor/mcp.json, then sign in when Cursor prompts you (Settings → MCP shows the server's status).

{ "mcpServers": { "agent-recall": { "url": "https://agentrecallx.com/mcp" } } }

claude.ai: Settings → Connectors → Add custom connector, and paste the URL https://agentrecallx.com/mcp (on plans where custom connectors are available).

Any other MCP client that supports Streamable HTTP with OAuth: give it the URL and nothing else. It finds the sign-in from the server's 401 response.

• 🔒 Private, in the EU. Your memory is visible only to your account and stored in Frankfurt. No ads, analytics or trackers. Privacy policy
• 📏 Limits. 100 MB of memory and 120 requests per minute per user. Reads keep working when you are full.
• ✋ Corrections wait for approval. An agent can only propose a correction here; it becomes a HARD RULE for your other agents once approved. You approve or reject them yourself on the review page at /review (sign in with the same account); the operator does not have to read your memory. How it works
• 🛠️ Run your own. The same server as a Compose + Caddy kit for one Ubuntu box: docs/hosted-server.md

For agents

[!NOTE] You are an AI agent reading this. AgentRecall is the user's memory across sessions and across agents. If its tools are connected, run this loop without being asked. If they are not, offer your human one of the two installs: Hosted above or Local below. Saying "noted" is not saving: only a tool call saves.

session begins              → session_start               first, before you act
a fact or decision to keep  → remember(content)
the human corrects you      → check(human_correction: { rule, why, applies_when })
before publish/push/delete  → check(action_description)   obey verdict "blocked"
past context would help     → recall(query)               safe any time
"save", or before you stop  → session_end(summary, insights, state)

• Hosted server: corrections you record are staged for the owner's approval. Tell the human it is waiting for the owner.
• Tools (default 5): session_start · remember · recall · check · session_end. Details in MCP tools.
• Don't claim you will remember something without calling a tool. Don't paste the whole memory back to the human; surface only what changes your next action. Don't store secrets, tokens or credentials.
• Machine-readable summary: llms.txt.

<details> <summary>Tell your human what you installed, in one breath</summary>

"I connected AgentRecall. When you correct me, I save it as a rule, and at the start of every session, in any agent you use, I load those rules before I act, so you shouldn't have to say the same thing twice. Say 'save' anytime and I'll checkpoint."

Local install: the memory is plain markdown in ~/.agent-recall/ and nothing leaves the machine. Hosted: it lives in your private space on agentrecallx.com (privacy).

</details>

Local install

Fully offline. Memory is plain markdown in ~/.agent-recall/; by default nothing leaves your machine (the Supabase mirror, Telegram reports and cloud embeddings are all opt-in).

MCP server: for agents

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

# Codex
codex mcp add agent-recall -- npx -y agent-recall-mcp

// Cursor: .cursor/mcp.json   ·   Windsurf: ~/.codeium/windsurf/mcp_config.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"] } } }

Hooks: Claude Code runs the loop for you

Optional. Locally, Claude Code hooks fire memory without agent discipline. Install the CLI (npm i -g agent-recall-cli gives you ar) and wire the hooks you want in ~/.claude/settings.json:

{
  "hooks": {
    "SessionStart":     [{ "hooks": [{ "type": "command", "command": "ar hook-start" }] }],
    "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "ar hook-correction" },
                                     { "type": "command", "command": "ar hook-save" }] }],
    "PreToolUse":       [{ "matcher": "Bash", "hooks": [{ "type": "command", "command": "ar hook-pretool" }] }],
    "Stop":             [{ "hooks": [{ "type": "command", "command": "ar hook-end" }] }]
  }
}

Command	Claude Code hook	What it does
ar hook-start	SessionStart	Injects the cards (owner, hard rules, state). AGENT_RECALL_SESSION_START_MODE=full for every section
ar hook-correction	UserPromptSubmit	Captures corrections silently
ar hook-ambient	UserPromptSubmit	Injects relevant memories (≥2-word overlap floor)
ar hook-save	UserPromptSubmit	"save" / "retain" → prompts session_end
ar hook-pretool	PreToolUse	Warns on npm publish, git push, rm -rf, deploy, DROP TABLE
ar hook-end	Stop	Auto-saves the journal if not saved today
ar health	—	Recent hook failures (fail-loud)
ar identity set <file>	—	Owner identity card, loaded first by every session

Skill: Claude Code

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

SDK: JS/TS apps

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

Each instance gets its own isolated root (AsyncLocalStorage), so concurrent instances never share state.

CLI: terminal, CI, hooks

npm i -g agent-recall-cli   # provides the `ar` command
ar recall "rate limiting"
ar bootstrap                # find git repos, Claude AutoMemory, CLAUDE.md (read-only)
ar bootstrap --import       # import what it found (secrets are skipped)

---

<p align="center"> <b>Below:</b> <a href="#why-agentrecall">Why</a> · <a href="#the-session-loop">Session loop</a> · <a href="#mcp-tools">MCP tools</a> · <a href="#the-nature-of-memory--5-layers">5 memory layers</a> · <a href="#how-memory-compounds">How memory compounds</a> · <a href="#the-math"><b>The math</b></a> · <a href="#measured-not-promised">Measured</a> · <a href="#compared-to-other-memory-tools">Compared</a> · <a href="#optional-extras">Extras</a> · <a href="#architecture">Architecture</a> · <a href="#platforms">Platforms</a> · <a href="#community">Community</a> </p>

Why AgentRecall

The problem is not memory. It is distance. You think in intuition, fragments and things you never say out loud. An agent works in tokens and literal instructions. That gap is structural: a bigger context window does not close it, and neither does a longer chat log. We call it Intelligent Distance.

AgentRecall does not pretend the gap goes away. It does three things with it:

• Makes it visible. Before a risky step the agent states what it thinks you want (check), so a misunderstanding surfaces before the work is done.
• Measures it. Each correction it captures is one reading of the gap. When the same situation returns, the outcome is recorded as heeded or recurred. The instrument is young and the numbers are small: see Measured, not promised.
• Shortens it. A correction made to one agent is loaded by every connected agent at the start of its next session (on the hosted server, once you approve it), so the next one starts closer to you than the last.

The bar is one question: does the agent behave measurably differently in session 50 than in session 1, with the same person? Memory is a component of that; it is not the product. The full specification is the Intelligent Distance Protocol.

Here is what that looks like in practice.

You tell your agent "don't bump the version without asking." It apologizes, fixes it, and the session ends. Next week a fresh session does it again, or a different agent does, because the correction lived in a chat log nobody reads.

AgentRecall turns that sentence into a structured, persistent rule, puts it in front of the next agent before it acts, whichever agent that is, and records whether the mistake came back.

── session 3 · Claude Code ──────────────────────────────
you   › no — never bump the version without asking me first
agent › check(human_correction: { rule, why, applies_when: [release, npm] })
        ✓ saved · severity p0

── session 9 · Codex, no chat history ───────────────────
session_start › project "my-app" · 1 critical correction
                watch_for: version bump → ask the owner first
you   › ship the fix
agent › Fix is merged. Want me to bump to 1.4.1, or leave the version?
        outcome recorded: heeded

_{Illustrative transcript. On the hosted server, the correction in session 3 waits for approval before session 9 loads it.}

AgentRecall is two things:

1. A governed corrections ledger. Every correction ("not that version", "put this section first", "ask before you assume") becomes a structured record (severity, evidence, applies_when, retraction, outcome) that persists across sessions, projects, agents and restarts. Export format: corrections-export/v1, scrubbed on egress.
2. A measurement instrument. Each correction accumulates retrieved_count, and every time the agent meets the same situation the outcome is logged as heeded or recurred. No public benchmark measures that step; we built the harness first and publish what it finds, including the unflattering numbers.

The session loop

flowchart LR
    A([session start]) --> B["/arstart · session_start<br/>load rules + context"]
    B --> C{work}
    C -->|need past knowledge| D["/arrecall · recall"]
    D --> C
    C -->|corrected| R["check<br/>human_correction"]
    R --> L[(corrections<br/>ledger)]
    C -->|risky action| K["check<br/>action_description"]
    L -.-> K
    C --> E["/arsave · session_end<br/>journal + compound"]
    E --> F([session end])
    L -. watch_for .-> B
    F -. every K sessions .-> G["/arreflect<br/>consolidate"]
    G -.-> A

Command	When	What it does
/arstart	First, every session	OPEN. No args → status board across all projects → pick → load that project's rooms, corrections and task recall. /arstart <slug> loads directly; /arstart bootstrap imports existing projects.
/arsave	Last, every session	SAVE. Journal + palace consolidation + awareness compounding. /arsave all merges every parallel session of the day.
/arrecall	Mid-session	SEARCH. Prior fixes, decisions, patterns for the current task.
/arreflect	Every K sessions	CONSOLIDATE. Confirm recurrences, cluster new error classes, propose rule re-abstractions (rule edits stay owner-gated).

Without /arstart, a fresh agent has zero orientation. Without /arsave, nothing compounds. The slash commands are Claude Code commands from commands/; in other agents, and on the hosted server, the same loop runs through the tools.

MCP tools

Five tools ship by default, locally and hosted. Each description is written for the agent and says when to call it.

Tool	Call it	What it does
session_start	First, before acting	Default mode: "cards" loads the owner identity card, the HARD RULES and the project state card, nothing else; mode: "full" adds insights, continuity, rooms, captures and watch_for warnings
remember	The moment something is decided	Saves one fact; auto-routes to journal / palace room / awareness
recall	Whenever past context would help	Ranked search across every store (RRF), with useful feedback that re-weights future ranking
check	When corrected, and before risky or irreversible actions	Records a correction (human_correction: {rule, why, applies_when}; staged for approval on the hosted server). With action_description, matches the plan against known corrections and returns verdict: "blocked" when one overrides it
session_end	On save / exit	Writes the journal, promotes insights, records trajectory, rewrites the project state card (state), optionally opens/closes a pipeline phase

<details> <summary>More tools: <code>--full</code> and <code>AR_EXTRAS=1</code> (local)</summary>

Surface	Enable	Tools
Default	—	the 5 above
Full	npx -y agent-recall-mcp --full	+ check_action (pre-action matcher for publish / push / deploy)
Extras	--full + AR_EXTRAS=1	+ pipeline_open · pipeline_close · pipeline_list · pipeline_current · pipeline_show · register_rule · digest

List what your install exposes: npx -y agent-recall-mcp --list-tools. The hosted server never enables the extras.

</details>

[!IMPORTANT] The Automaticity Law: why only 5. Memory only compounds if it fires without being asked. Across 44 projects and weeks of real use, the pull tools (recall, memory_query) saw zero organic calls, including from the agent that built them. Push channels (session_start, session_end, correction hooks) are what change behavior. Every extra default tool costs definition tokens every session for no return. _{(Self-measured on the owner's store, 2026-06-12.)}

That is why the local install ships hooks, and why the hosted server sends every agent instructions to call session_start first and session_end before it stops.

The nature of memory — 5 layers

The cognitive-psychology taxonomy, mapped to plain files. Each layer forgets at a different speed, because human memory does.

#	Layer	Holds	Path	Forgets
1	Episodic	What happened, per session	journal/	fast — $S = 2$ days
2	Semantic	Topic facts with [[wikilinks]]: architecture, goals, blockers	palace/rooms/	barely — $S = 9999$ days, salience-ranked
3	Procedural	IF-THEN production rules	palace/skills/	by use
4	Narrative	Phases: goal → what was hard → how solved → synthesis	palace/pipeline/	never (history)
5	Correction	Rules the agent must follow — severity, evidence, outcomes	corrections/	never by time — only by retraction
+	Awareness	Cross-project insights promoted from repeated corrections	palace/awareness	confirmation-weighted

~/.agent-recall/                (hosted: one private copy of this tree per user)
├── projects/<slug>/
│   ├── journal/            episodic — one entry per session
│   ├── corrections/        behavioral rules + outcome ledger
│   └── palace/
│       ├── rooms/          semantic
│       ├── skills/         procedural
│       ├── pipeline/       narrative
│       ├── identity.md
│       └── awareness       cross-project insights
├── dreams/                 nightly consolidation reports
├── dashboard.html          human-readable
└── dashboard.json          agent-readable snapshot

All layers share one naming grammar, so an agent can compose a retrieval path from intent. Older files keep working through a legacy_path view — no migration.

How memory compounds

flowchart LR
    C["correction<br/>(check / hook)"] --> L[(ledger)]
    L --> S["session_start<br/>ranked by severity,<br/>proof, recency"]
    S --> O{"same situation<br/>again?"}
    O -->|heeded| P["proof_count +1<br/>stability × 1.3"]
    O -->|recurred| X["phantom<br/>→ /arreflect<br/>rewrites the rule"]
    P --> A["≥ 3 confirmations<br/>→ awareness<br/>(cross-project)"]
    X --> L

A correction gets stronger each time it is confirmed, weaker when it is marked unhelpful, and graduates to every project once it has been confirmed on three distinct (day, project) occasions. A rule that was saved but whose mistake came back is a phantom — the write cost was paid and behavior never changed — and gets re-written, not just re-saved.

The math

Most of the field ships "AI memory" as a black box. Every mechanism in AgentRecall is a formula you can read, with its constants in the source and an honest label:

Label	Meaning
🟢 GROUNDED	A published result restated exactly, or a constant tuned on real data with a reported metric
🟡 HAND-TUNED	Principled functional form; constants chosen by judgment, not fit to recall outcomes
🔴 ASPIRATIONAL	The claim is ahead of the math present — stated so, with the model that would close the gap

1 · Rank fusion — Reciprocal Rank Fusion 🟢

Palace, journal, insight and corrections each rank their own candidates; the lists are merged by rank, never by raw score, because the raw scores live on incomparable scales (Cormack, Clarke & Büttcher 2009 — the same $k$ Elasticsearch ships):

\mathrm{RRF}(d) \;=\; \sum_{\ell \,\in\, \text{lists}} \frac{w_\ell}{k + \mathrm{rank}_\ell(d)}, \qquad k = 60,\;\; w_\ell = 1

The optional semantic leg is just one more list with $w = 1.0$ — a weight measured, not chosen: 1.1 and 1.3 flooded the top-5.

[!NOTE] The math found a bug. Adjacent RRF ranks differ by only $\frac{1/(60+r)}{1/(61+r)} \approx 1.6\%$, so any post-fusion multiplier above ≈1.02 vaults an off-topic item over every on-topic one. The old ×3 / ×2 / ×1.3 "recent-item boost" did exactly that — top-5 filled with the last 72 h of diary lines. Removing it: 55.0% → 75.0% top-5 hit-rate on the golden set (twin-clone control, 2026-09-12).

2 · Forgetting — Ebbinghaus per source 🟢 form · 🟡 constants

R(t) = e^{-t/S}, \qquad S_{\text{journal}} = 2,\;\; S_{\text{knowledge}} = 180,\;\; S_{\text{palace}} = 9999 \text{ days}

3 · Spaced reinforcement — FSRS-lite 🟢 form · 🟡 constants

A two-component (stability, retrievability) simplification of FSRS-6 / SuperMemo — no difficulty term, because we never run review sessions:

R = e^{-\Delta t / S}, \qquad S_0 = 7\text{ d}, \qquad \underbrace{S' = 1.3\,S}_{\text{confirmed}}, \qquad \underbrace{S' = \max(1,\; 0.5\,S)}_{\text{marked wrong}}

Buckets: $R \ge 0.85$ hot · $\ge 0.6$ warm · $\ge 0.3$ cool · else archive candidate — surfaced on a dashboard, never auto-deleted.

4 · Salience — what a palace room is worth 🟡

\text{salience} = 0.30\,\text{recency} + 0.25\,\text{access} + 0.20\,\text{connections} + 0.15\,\text{urgency} + 0.10\,\text{importance}

with $\text{recency} = \max(0.05,\; \rho_c^{\,\text{days}})$, where the decay rate depends on category: goal $\rho = 0.99$ · architecture $0.98$ · decision / lesson $0.97$ · observation $0.95$ · blocker $0.90$. Self-reported importance is deliberately the weakest term — people mis-estimate it; what you actually use is the stronger signal.

5 · Learning from feedback — Beta–Bernoulli 🟢

Every recall result can be rated useful / not useful. The item's score is multiplied by twice its Laplace-smoothed posterior mean (neutral = ×1.0; the only post-fusion score change on default paths):

\mathbb{E}[\theta] = \frac{\text{pos}+1}{\text{pos}+\text{neg}+2}, \qquad \text{multiplier} = 2\,\mathbb{E}[\theta] \in (0, 2)

6 · Association — ACT-R activation 🟡 (opt-in AGENT_RECALL_ACTIVATION=1)

Memories cited together become linked. The associative term of ACT-R's declarative-memory equation (Anderson & Lebiere):

A_i = B_i + \sum_j W_j\, S_{ji}, \qquad S_{ji} = w_{ji}\, e^{-\Delta d / 30}, \qquad W_j = \tfrac{1}{|\text{context}|}

Re-rank: $\text{score}' = \text{score}\cdot\bigl(1 + 0.2\,\tfrac{x}{x+1}\bigr)$ — the $\tfrac{x}{x+1}$ squash keeps two incompatible scales from being summed, and is an exact no-op when there is no evidence.

7 · Paraphrase matching — set cosine 🟡 metric · 🟢 threshold

\cos(A,B) = \frac{|A \cap B|}{\sqrt{|A|\,|B|}}, \qquad \text{sim} = \max\bigl(\cos_{\text{concepts}},\; \cos_{\text{char-trigrams}}\bigr) \ge 0.20

Over stems + 13 hand-curated synonym groups ("publish / ship / release" collapse to one concept). It is fuzzy-lexical, not meaning. The 0.20 threshold is tuned by leave-one-out (predict-loo) as the highest-recall point that still holds 0% false positives.

8 · Promotion — admit, then vote 🟢

Nightly consolidation used to gate on $\tfrac{\text{obs}}{7}\times\text{recency} \ge 0.8$. At 2 AM the freshest journal is yesterday, so recency $\le 0.85$ and "3 observations in 7 days" scored $\tfrac{3}{7}\times 0.85 = 0.36$ — silently discarded for 22 nights, while uptime monitoring stayed green. The replacement separates admission from promotion:

\text{promote} \iff \#\{(\text{day},\,\text{project}) \text{ confirmations}\} \ge 3

and every night now writes a yield record, so a zero-output night is classified (empty-corpus · filtered · already-known · errored) instead of looking healthy.

9 · Measuring behavior change — heed rate + Wilson interval 🟢

\text{heed} = \frac{\text{heeded}}{\text{heeded} + \text{recurred}}, \qquad
\text{CI}_{95} = \frac{\hat p + \frac{z^2}{2n} \;\pm\; z\sqrt{\frac{\hat p(1-\hat p)}{n} + \frac{z^2}{4n^2}}}{1+\frac{z^2}{n}}, \quad z = 1.96

Small $n$ gets an honest, wide interval instead of a confident point. Events are tiered by evidence (heeded_verified · heeded_checkaction · heeded_default · recurred_verified · recurred_selfreport), and every KPI surface shows both tiers as a range — absence of evidence is not credited as "heeded."

10 · Calibrated confidence 🟡

\text{conf} = \frac{\text{score}}{0.12}\;(\text{local RRF}) \;\;\big|\;\; \frac{\text{score}}{0.049}\;(\text{Supabase RRF}) \;\;\big|\;\; \cos\;(\text{vectors}) \;\;\longrightarrow\;\; \text{high} \ge .66,\; \text{med} \ge .40,\; \text{low} \ge .20

<details> <summary>In the codebase, deliberately <b>not</b> wired in: Modern Hopfield re-rank</summary>

Ramsauer et al. 2020, implemented with a numerically stable softmax, $\beta = 8$:

\xi^{\text{new}} = X^{\top}\operatorname{softmax}(\beta X \xi), \qquad E = -\tfrac{1}{\beta}\log\sum_i e^{\beta\langle x_i,\xi\rangle} + \tfrac12\lVert\xi\rVert^2

Not on the default path: the co-citation graph is sparse by construction, and Hopfield's exponential-capacity argument assumes a dense regime — it would mostly attend to non-edges. The linear ACT-R sum is the right primitive for a sparse graph.

</details>

Open problem 🔴 — does redundancy reconstruct intent?

Today, accumulated corrections are clustering + decay + set-cosine: a tally, not a posterior. Calling that "intent reconstruction" would overstate it. The model that would earn the phrase treats each correction as a noisy sample of a latent preference $\theta$, with $x_i = \theta + \varepsilon_i,\; \varepsilon_i \sim \mathcal N(0, \sigma^2 I)$ and prior $\theta \sim \mathcal N(\mu_0, \tau^2 I)$:

\operatorname{Var}[\theta \mid x_{1..N}] = \Bigl(\frac{1}{\tau^2} + \frac{N}{\sigma^2}\Bigr)^{-1} = O\!\left(\frac{\sigma^2}{N}\right),
\qquad \mathrm{SNR}_N = \frac{\lVert \mu_N \rVert^2}{\operatorname{tr}\operatorname{Var}[\theta \mid x_{1..N}]}

Falsifiable claim: $\mathrm{SNR}_N$ rises monotonically for a consistent correction stream and stalls when corrections conflict. Want to build it? This is the most important open problem in the repo.

_{Full derivations, inputs, and every constant's provenance: packages/core/src/MATH.md.}

Measured, not promised

Agent-memory benchmarks test retrieval. None tests whether a correction changes what a fresh agent does. Here is what our own instrument says — including the parts that make us look bad.

	Metric	Value	Source
🔁	Retrieval hit@5, golden fixture v1 (26 queries, hash-locked)	73.1% keyword [53.9, 86.3]<br>80.8% + local embeddings [62.1, 91.5]	npm run bench:golden
🔁	session_start context injected, median (fixture, no cards)	88 tokens (cards default; 231 with --mode full)	npm run bench:injection
🔁	session_start p95 warm / recall p95	97 ms / 209 ms	npm run bench:latency
🔁	Correction-transfer fixture gate	exact match	npm run bench
🔒	Real corrections captured (dual-blind audit, n = 59)	35.3% [17.3, 58.7]	UPDATE-LOG.md §M2
🔒	Heed rate, evidence-grounded	0 / 3 events	scripts/eval/baselines/rmr-baseline-2026-07-03.json
🔒	Offline correction-transfer recall	0 / 4 [0, 49]	scripts/eval/baselines/correction-transfer-real-2026-07-03.json
🔒	Golden eval on a lived-in store (keyword → embeddings)	75% → 90%	fix7 report, 2026-09-12
🔒	session_start on a lived-in store	1,489 tokens · 363 ms p95	UPDATE-LOG.md §C2

_{🔁 regenerates from this repo · 🔒 self-measured on the owner's private store, not reproducible here. Brackets are 95% intervals. The 80.8% embeddings leg is measured locally with the opt-in model (CI never downloads it, so no artifact is committed). Timings are machine-dependent; CI gates schema and determinism, never timing values. All figures are for the local install; the hosted server adds network time.}

<details> <summary>What these numbers mean</summary>

We captured about a third of real corrections in our own use. The heed instrument used to default to "heeded" without evidence — it was reset to "unknown," so 0/3 is the honest starting point, not a regression (the pre-reset 92.5% is an instrument-biased upper bound; do not cite it). Offline transfer scores 0 on our corpus because 32 active corrections across 19 projects is too sparse to front-run mistakes — a density problem, not a retrieval one (confirmed 5× internally). Transfer recall cannot support a point estimate below 39 classes (claim-gate ledger, benchmark spec §2.6).

The fixture numbers are smaller than the lived-in ones because golden-v1 is synthetic and thin (3 projects). Every remaining fixture miss is a committed structural trap: pipeline dir, loose rooms file, cross-project silo.

Reproduce everything: docs/eval/REPRODUCE.md.

</details>

Compared to other memory tools

	Typical agent memory (Mem0, Zep/Graphiti, Letta, Supermemory)	AgentRecall
Optimizes for	Recalling facts	Not repeating mistakes
Corrections	Another memory row	Governed ledger: severity, evidence, retraction, outcome
Measures	Retrieval (LongMemEval, LoCoMo)	Retrieval and behavior change across sessions
Storage	Hosted service or DB	Markdown on your disk, or a private folder per user on the hosted server (same files)
Ranking	Usually opaque	Every formula and constant labelled (see The math)
Per-session cost	~7k tokens/query (Mem0's published figure)	~88 tokens at session_start (cards default; fixture, no cards)

_{Competitor figures are their own published numbers, not measured side by side. Landscape: docs/research/agent-memory-landscape-2026-07.md.}

Optional extras

<details> <summary>🔎 <b>Semantic recall</b> — 100% local embeddings</summary>

Keyword recall can't reach a memory phrased differently ("semver increment" vs "one version bump per release"). The opt-in semantic leg uses a local ONNX model and joins the same RRF fusion as one more list.

ar embeddings setup     # one-time: local runtime (~380 MB) + model (~145 MB), cached
ar embeddings rebuild   # incremental — only new/changed content embeds
export AGENT_RECALL_EMBEDDINGS=1
ar embeddings status

Default	OFF — flag off is byte-identical to keyword recall
Model	paraphrase-multilingual-MiniLM-L12-v2; Chinese ↔ English cross-lingual; e5 family via AGENT_RECALL_EMBEDDINGS_MODEL
Network	Only setup downloads. Recall and rebuild run with remote fetch hard-disabled
Degradation	Missing/corrupt index → keyword results with the reason in semantic_leg metadata — never an error
Security	Index stores content-hash → vector only (no text); semantic hits pass the same trust/scope/fence stages
Cloud seam	A dormant OpenAI embedding path exists for vector recall; it activates only with AGENT_RECALL_CLOUD_EMBEDDINGS=1 and OPENAI_API_KEY set together — an ambient OPENAI_API_KEY alone never sends anything off-machine

</details> <details> <summary>🌙 <b>Dreaming</b> — nightly consolidation</summary>

Does	Result
Mine patterns across projects	Corrections confirmed on ≥3 (day, project) occasions promote to palace/awareness
Salience decay	Low-signal rooms fade
Journal rollups	Entries > 30 days compress into summary rooms
Yield accounting	Every night classified; zero-output nights can't hide
Report	~/.agent-recall/dreams/YYYY-MM-DD.md, optionally Telegram

Needs a live Claude Code login (claude login if it stops).

</details> <details> <summary>🧪 <b>Experimental:</b> recurrence &amp; reflection harness kit</summary>

experimental/harness-kit/ — Claude Code hooks that answer "did the correction change behavior?": a SessionStart scoreboard, an error-class taxonomy with mechanical phantom detection (violation dated after its rule), an overdue-reflection nudge, and an optional model-dispatch guard. North-star: post-re-abstraction phantom rate → 0. First run: 8 error classes and 18 phantoms in 109 corrections; 6 rules re-abstracted the same day. Python 3 stdlib only.

</details>

Architecture

Local and hosted are the same server with two front doors. Both MCP entry points assemble their server in build-server.ts, and everything runs on agent-recall-core.

<p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="assets/readme/architecture-dark.svg"> <img src="assets/readme/architecture-light.svg" alt="Architecture. Local mode: the ar CLI with hooks, the SDK, and agent-recall-mcp over stdio write to ~/.agent-recall on your disk. Hosted mode: agents reach Caddy (deploy/hosted) over HTTPS, then agent-recall-server (packages/mcp-server/src/http) with OAuth, tokens and limits. Both MCP entry points build their server with build-server.ts, and everything runs on agent-recall-core. Hosted memory is one folder per user under DATA/tenants."> </picture> </p>

packages/
├── core/                    storage, retrieval, math, tool logic          agent-recall-core
├── mcp-server/              MCP wrappers                                  agent-recall-mcp
│   └── src/
│       ├── build-server.ts  one server assembly, shared by both modes
│       ├── index.ts         local: stdio, one user           (npx agent-recall-mcp)
│       └── http/            hosted: HTTPS, OAuth, tokens, per-user limits (agent-recall-server)
├── sdk/                     programmatic API                              agent-recall-sdk
└── cli/                     the `ar` command + hooks                      agent-recall-cli
deploy/hosted/               Compose + Caddy kit for a hosted server on one Ubuntu box

	Local	Hosted
Transport	stdio, one process per agent	Streamable HTTP, POST /mcp, a fresh server per request
Who	You	Many users; every request runs in its own tenant scope
Storage	~/.agent-recall/	DATA/tenants/<uid>/, the same file layout
Sign-in	—	OAuth 2.1 (GitHub, Google) or operator-issued tokens
Lifecycle	Hooks fire session_start / session_end	The server tells the agent to call them
Corrections	Activate directly	Staged until approved

flowchart LR
    Q[query] --> T[tokenize · stem<br/>synonyms · IDF]
    T --> P[palace<br/>0.9 key + 0.1 salience]
    T --> J[journal<br/>0.5 recency + 0.5 exact]
    T --> I[insights<br/>relevance · exact · confirm]
    T --> K[corrections<br/>exact · severity · proof]
    Q -. opt-in .-> V[local embeddings<br/>cosine top-8]
    P & J & I & K & V --> F["RRF  Σ w/(60+rank)"]
    F --> B["× Beta feedback"]
    B --> C[calibrated confidence]
    C --> R[results + alsoLinked]

All memory is markdown files. An optional Supabase mirror (local installs only) adds pgvector recall with the same RRF fusion. Writes go through a progress-aware file lock with NTFS-safe release; alignment and feedback logs are append-only NDJSON. Running your own hosted server: docs/hosted-server.md.

Platforms

Platform	Local	Hosted (agentrecallx.com)
Claude Code	MCP + skill + hooks (primary)	claude mcp add --transport http, then /mcp → Authenticate
Codex	MCP (stdio)	codex mcp add --url, GitHub sign-in
Cursor	MCP (stdio)	mcp.json with the url
claude.ai	—	Custom connector with the URL
Windsurf · VS Code (Copilot)	MCP (stdio)	Any Streamable HTTP + OAuth client; not tested yet
Any JS/TS app	agent-recall-sdk	—
Terminal / CI	ar	—

CI runs build + regression + tests on ubuntu-latest and windows-latest.

Community

AgentRecall is built in the open, and it gets better with every person who uses it and reports back.

• 💬 Telegram: questions, feedback, requests
• 🗣️ GitHub Discussions: field reports, benchmark numbers, adapters, 中文区
• 🐛 GitHub Issues: bugs and features. For the hosted server, please don't post personal data in issues; write to the contact in PRIVACY.md
• 📦 npm: agent-recall-mcp · agent-recall-sdk · agent-recall-cli

[!TIP] The 15-minute contribution that matters most. The field has vendor-selected positives and no external baselines for behavior change. Use AgentRecall locally for a week, then:

git clone https://github.com/Goldentrii/AgentRecall-X.git && cd AgentRecall-X
npm ci && npm run bench    # reads your local ~/.agent-recall corpus

Post the result in Discussions → Benchmark Numbers; a low score is a valid result. More in CONTRIBUTORS-WANTED.md.

Contributors

<a href="https://github.com/Goldentrii/AgentRecall-X/graphs/contributors"><img src="https://contrib.rocks/image?repo=Goldentrii/AgentRecall-X" alt="Contributors"></a>

Thanks to @buer5, @lonelyhty and 雷昊 for the Windows portability work and fixes that shipped in 3.5.x.

<a href="https://mcpvault.io/servers/agentrecall-x/health?utm_source=external_badge&amp;utm_medium=referral&amp;utm_campaign=mcp_health_report"><img src="https://mcpvault.io/badge/agentrecall-x.svg" alt="MCPVault: claimed"></a>

<a href="https://star-history.com/#Goldentrii/AgentRecall-X&Date"><img src="https://api.star-history.com/svg?repos=Goldentrii/AgentRecall-X&type=Date" alt="Star history" width="600"></a>

Links

• docs/hosted-server.md: run, operate and secure a hosted server · PRIVACY.md: the hosted service's privacy policy
• README.full.md: full reference: SDK API, CLI, every tool parameter
• packages/core/src/MATH.md: every formula, constant and label
• docs/eval/REPRODUCE.md: regenerate every 🔁 number
• CHANGELOG.md · UPDATE-LOG.md: what changed, and the reasoning
• Correction-transfer benchmark spec · Agent-memory landscape 2026
• SKILL.md: Claude Code skill · AGENTS.md: for agents working on this repo · llms.txt: this README for machines
• README artwork: assets/readme/ (generated by assets/readme/build/)
• Previous README: docs/archive/README-2026-10-13.md

Contributing

PRs welcome. Open an issue first for anything substantive — the design is opinionated and grounded in published research, and we want changes grounded the same way: a formula, a label, and a measurement.

License

MIT — see LICENSE.