agent-recall-mcp 3.2.0 → 3.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +140 -228
  2. package/dist/index.js +1 -1
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -1,195 +1,167 @@
1
1
  <p align="center">
2
- <h1 align="center">agent-recall-mcp</h1>
3
- <p align="center"><strong>Give your AI agent a brain that survives every session.</strong></p>
2
+ <h1 align="center">AgentRecall</h1>
3
+ <p align="center"><strong>The Intelligent Distance Protocol for AI Agents</strong></p>
4
+ <p align="center">Minimize information loss between human and AI — across every session, every agent, every project.</p>
4
5
  </p>
5
6
 
6
7
  <p align="center">
7
8
  <a href="https://www.npmjs.com/package/agent-recall-mcp"><img src="https://img.shields.io/npm/v/agent-recall-mcp?style=flat-square&color=5D34F2" alt="npm"></a>
8
9
  <a href="https://github.com/NovadaLabs/AgentRecall/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-brightgreen?style=flat-square" alt="License"></a>
9
- <img src="https://img.shields.io/badge/MCP-12_tools-orange?style=flat-square" alt="MCP Tools">
10
- <img src="https://img.shields.io/badge/node-%3E%3D18-green?style=flat-square" alt="Node">
10
+ <img src="https://img.shields.io/badge/MCP-12_tools-orange?style=flat-square" alt="Tools">
11
+ <img src="https://img.shields.io/badge/protocol-Intelligent_Distance-5B2D8E?style=flat-square" alt="Protocol">
11
12
  <img src="https://img.shields.io/badge/cloud-zero-blue?style=flat-square" alt="Zero Cloud">
12
13
  </p>
13
14
 
14
- <p align="center">
15
- MCP server for persistent agent memory — session journals, structured JSON state,<br>
16
- Think-Execute-Reflect quality loops, cache-aware cold start, and alignment detection.<br>
17
- Works with <strong>Claude Code, Cursor, VS Code Copilot, Windsurf, Claude Desktop</strong>, and any MCP client.
18
- </p>
15
+ ---
16
+
17
+ ## Intelligent Distance The Core Idea
18
+
19
+ > *"The gap between human intelligence and AI intelligence is structural and permanent — not a temporary technology problem."*
19
20
 
20
- <p align="center"><strong>Zero cloud. Zero telemetry. All data stays on your machine.</strong></p>
21
+ Humans are **born** (embodied experience, emotion, survival pressure). Machines are **made** (rules, deterministic). AI is **trained** (statistical co-occurrence over data). Three different cognitive origins produce three different ways of understanding the world. This gap will not close as AI improves — because the difference is in **origin**, not capability.
22
+
23
+ **The conventional approach:** make AI more human-like → close the gap.
24
+
25
+ **The Intelligent Distance approach:** accept the gap as permanent → design a **protocol** that minimizes information loss when translating between the two intelligence types.
26
+
27
+ ```
28
+ Human says: "click all"
29
+ Agent hears: "click the main things"
30
+ Gap: "all" ≠ "main things"
31
+
32
+ Human says: "done means identical"
33
+ Agent thinks: "close enough"
34
+ Gap: "identical" ≠ "close enough"
35
+
36
+ Human gives: scattered, non-linear instructions
37
+ Agent picks: one instruction, ignores the rest
38
+ Gap: the connective tissue between points is lost
39
+ ```
40
+
41
+ **AgentRecall doesn't try to close this gap. It builds the protocol to navigate it.**
21
42
 
22
43
  ---
23
44
 
24
- ## Why AgentRecall?
45
+ ## How AgentRecall Bridges the Gap
25
46
 
26
- | Problem | How AgentRecall Solves It |
27
- |---------|--------------------------|
28
- | Agent forgets everything between sessions | Three-layer memory persists state across sessions |
29
- | Agent repeats the same mistakes | Failures section + feedback promotion catches patterns |
30
- | Agent says "done" when it's not | Think-Execute-Reflect loop with quality scoring |
31
- | Cold start takes too long (28 journal files) | Cache-aware cold start: hot/warm/cold in <1 second |
32
- | Human has to explain context every time | JSON state layer transfers context agent-to-agent |
33
- | No one knows what the agent actually did | Structured counts: "built 11 pages, 35 tabs" not "went well" |
47
+ | Intelligent Distance Gap | AgentRecall Tool | What It Does |
48
+ |--------------------------|-----------------|-------------|
49
+ | Agent forgets what human said yesterday | `journal_read` + `journal_cold_start` | Persistent memory 3-layer, cache-aware |
50
+ | Agent misunderstands human intent | `alignment_check` | Records confidence + assumptions human corrects BEFORE work |
51
+ | Agent contradicts a prior decision | `nudge` | Detects contradiction surfaces it BEFORE damage |
52
+ | Agent says "done" but human disagrees | Think-Execute-Reflect loop | Quality scoring with COUNTS ("built 11 pages, 35 tabs"), not feelings ("went well") |
53
+ | Agent builds from imagination, not data | `journal_state` (JSON) | Structured state transfers agent-to-agent — no prose interpretation |
54
+ | Agent repeats the same mistake | Failures section + `context_synthesize` | Cross-session pattern detection promoted to permanent memory |
55
+ | Next agent starts from zero | `journal_cold_start` (v3) | Hot/warm/cold cache — loads 3 files instead of 28 |
56
+
57
+ **Memory solves forgetting. AgentRecall solves misunderstanding.**
34
58
 
35
59
  ---
36
60
 
37
61
  ## Quick Start
38
62
 
39
- ### Claude Code
63
+ ### MCP Server (any agent)
40
64
 
41
65
  ```bash
66
+ # Claude Code
42
67
  claude mcp add agent-recall -- npx -y agent-recall-mcp
43
- ```
44
68
 
45
- ### Cursor
46
-
47
- `.cursor/mcp.json`:
48
- ```json
49
- {
50
- "mcpServers": {
51
- "agent-recall": {
52
- "command": "npx",
53
- "args": ["-y", "agent-recall-mcp"]
54
- }
55
- }
56
- }
69
+ # Cursor — .cursor/mcp.json
70
+ { "mcpServers": { "agent-recall": { "command": "npx", "args": ["-y", "agent-recall-mcp"] } } }
71
+
72
+ # VS Code — .vscode/mcp.json
73
+ { "servers": { "agent-recall": { "command": "npx", "args": ["-y", "agent-recall-mcp"] } } }
57
74
  ```
58
75
 
59
- ### VS Code / Windsurf / Claude Desktop
76
+ ### Skill (Claude Code)
60
77
 
61
- Same pattern — add `npx -y agent-recall-mcp` as an MCP server command.
78
+ ```bash
79
+ mkdir -p ~/.claude/skills/agent-recall
80
+ curl -o ~/.claude/skills/agent-recall/SKILL.md \
81
+ https://raw.githubusercontent.com/NovadaLabs/AgentRecall/main/SKILL.md
82
+ ```
83
+
84
+ Say **"save"** to journal. Say **"read the latest journal"** to resume.
62
85
 
63
86
  ---
64
87
 
65
- ## 12 Tools
88
+ ## 12 MCP Tools
66
89
 
67
90
  ### Session Memory (6 tools)
68
91
 
69
- | Tool | What it does |
70
- |------|-------------|
71
- | `journal_read` | Read entry by date or `"latest"`. Filter by section. |
72
- | `journal_write` | Append to or replace today's journal. |
73
- | `journal_capture` | Lightweight Q&A capture — one question + answer, tagged. |
74
- | `journal_list` | List recent entries (date, title, momentum). |
75
- | `journal_search` | Full-text search across all entries. |
76
- | `journal_projects` | List all tracked projects on this machine. |
92
+ | Tool | Purpose |
93
+ |------|---------|
94
+ | `journal_read` | Read entry by date or "latest". Filter by section. |
95
+ | `journal_write` | Write or update journal content |
96
+ | `journal_capture` | Lightweight L1 Q&A capture |
97
+ | `journal_list` | List recent entries |
98
+ | `journal_search` | Full-text search across history |
99
+ | `journal_projects` | List all tracked projects |
77
100
 
78
- ### v3 Architecture (3 tools) — NEW in v2.1.1
101
+ ### v3 Architecture (3 tools) — NEW
79
102
 
80
- | Tool | What it does |
81
- |------|-------------|
82
- | `journal_state` | **Layer 1 JSON state** — read/write structured session data. Agent-to-agent handoffs use JSON (milliseconds, no prose parsing). |
83
- | `journal_cold_start` | **Cache-aware cold start** — HOT (today+yesterday, full state), WARM (2-7 days, brief only), COLD (older, count only). Loads 3 files instead of 28. |
84
- | `journal_archive` | **Archive old entries** — moves entries older than N days to `archive/` with one-line summaries. Keeps journal/ clean. |
103
+ | Tool | Purpose |
104
+ |------|---------|
105
+ | `journal_state` | **JSON state layer** — structured read/write for agent-to-agent handoffs (milliseconds, no prose) |
106
+ | `journal_cold_start` | **Cache-aware cold start** — HOT (today+yesterday), WARM (2-7 days), COLD (7+ days) |
107
+ | `journal_archive` | **Archive old entries** — moves to `archive/` with summaries, keeps journal/ clean |
85
108
 
86
109
  ### Alignment & Synthesis (3 tools)
87
110
 
88
- | Tool | What it does |
89
- |------|-------------|
90
- | `alignment_check` | Record understanding, confidence, assumptions, and human corrections. |
91
- | `nudge` | Surface contradictions between current input and prior decisions. |
92
- | `context_synthesize` | Cross-session synthesis goal evolution, decision history, patterns. |
111
+ | Tool | Purpose |
112
+ |------|---------|
113
+ | `alignment_check` | Record confidence + assumptions + human corrections |
114
+ | `nudge` | Surface contradiction between current and past input |
115
+ | `context_synthesize` | L3 synthesis: patterns, contradictions, goal evolution |
93
116
 
94
117
  ---
95
118
 
96
- ## Architecture
119
+ ## How Alignment Detection Works
120
+
121
+ When an agent isn't sure it understands:
97
122
 
98
123
  ```
99
- ┌─────────────────────────────────────────────────────────────┐
100
- │ Agent Session │
101
- │ │
102
- │ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │
103
- │ │ L1: Working │ │ L2: Journal │ │ L3: Synthesis │ │
104
- │ │ Memory │ │ (daily) │ │ (cross-session) │ │
105
- │ │ ~50 tokens │ │ ~800 tokens │ │ ~200 tokens │ │
106
- │ │ │ │ │ │ │ │
107
- │ │ journal_ │ │ journal_ │ │ context_ │ │
108
- │ │ capture │ │ write/read │ │ synthesize │ │
109
- │ └──────┬───────┘ └──────┬───────┘ └────────┬─────────┘ │
110
- │ │ synthesized │ synthesized │ │
111
- │ └────────►─────────┘────────►───────────┘ │
112
- │ │
113
- │ ┌──────────────────────────────────────────────────────┐ │
114
- │ │ v3: JSON State Layer (agent-to-agent, no prose) │ │
115
- │ │ journal_state → .state.json alongside .md │ │
116
- │ └──────────────────────────────────────────────────────┘ │
117
- │ │
118
- │ ┌──────────────────────────────────────────────────────┐ │
119
- │ │ v3: Cache Layer (hot/warm/cold) │ │
120
- │ │ journal_cold_start → loads 3 files, not 28 │ │
121
- │ └──────────────────────────────────────────────────────┘ │
122
- └─────────────────────────────────────────────────────────────┘
124
+ ALIGNMENT CHECK:
125
+ - Goal: Build a REST API for user management
126
+ - Confidence: medium
127
+ - Assumptions: PostgreSQL, no auth yet, CRUD only
128
+ - Unclear: Should this include role-based access?
123
129
  ```
124
130
 
125
- ---
131
+ Human confirms or corrects. The delta is logged. Over time, patterns reveal where misunderstanding is most likely.
126
132
 
127
- ## Cache-Aware Cold Start (v3)
133
+ ## How Nudge Protocol Works
128
134
 
129
- ```
130
- ┌─ HOT (0-1 day) ─────────────────────────────────┐
131
- │ Full JSON state + brief from markdown │
132
- │ → Everything the next agent needs │
133
- └──────────────────────────────────────────────────┘
134
-
135
- ┌─ WARM (2-7 days) ────────────────────────────────┐
136
- │ Brief summary only (first 2KB of journal) │
137
- │ → "What happened this week" context │
138
- └──────────────────────────────────────────────────┘
139
-
140
- ┌─ COLD (7+ days) ─────────────────────────────────┐
141
- │ Count only. Use journal_read for full content. │
142
- │ Use journal_archive to move to archive/ folder. │
143
- └──────────────────────────────────────────────────┘
144
- ```
135
+ When the agent detects the human contradicts a prior decision:
145
136
 
146
- ---
147
-
148
- ## JSON State (v3) Agent-to-Agent Format
149
-
150
- ```json
151
- {
152
- "version": "2.1.1",
153
- "date": "2026-04-07",
154
- "project": "my-project",
155
- "completed": [
156
- { "task": "built dashboard", "result": "11 pages, 35 tabs" }
157
- ],
158
- "failures": [
159
- { "task": "extraction", "what_went_wrong": "missed sub-tabs", "root_cause": "context fatigue", "fixed": true }
160
- ],
161
- "state": {
162
- "genome": { "status": "v3.2", "details": "8 dimensions" }
163
- },
164
- "next_actions": [
165
- { "priority": "P0", "task": "verify against real site" }
166
- ],
167
- "insights": [
168
- { "claim": "extraction quality = replication quality", "confidence": "high", "evidence": "4 sites tested" }
169
- ],
170
- "counts": { "pages": 91, "tabs": 35, "api_routes": 3 }
171
- }
137
+ ```
138
+ NUDGE:
139
+ - You decided Clerk for auth on March 25.
140
+ - Now you're asking for custom auth from scratch.
141
+ - Has the goal changed, or should we stick with Clerk?
172
142
  ```
173
143
 
174
- The next agent reads this in milliseconds. No prose parsing. No ambiguity.
144
+ Not the agent being difficult it's helping the human **clarify their own thinking.**
175
145
 
176
146
  ---
177
147
 
178
- ## Storage
148
+ ## Three-Layer Memory + v3 Cache
179
149
 
180
150
  ```
181
- ~/.agent-recall/
182
- └── projects/
183
- └── {project}/
184
- └── journal/
185
- ├── index.md ← auto-generated
186
- ├── 2026-04-07.md ← L2: daily journal (markdown)
187
- ├── 2026-04-07.state.json v3: structured state (JSON)
188
- ├── 2026-04-07-log.md ← L1: raw Q&A capture
189
- ├── 2026-04-07-alignment.md ← alignment checks
190
- └── archive/ ← v3: cold storage
191
- ├── index.md ← one-line summaries
192
- └── 2026-03-25.md ← archived entries
151
+ ┌─────────────────────────────────────────────────────────┐
152
+ L1: Working Memory [per-turn, ~50 tok] "What happened"│
153
+ │ ↓ synthesized into │
154
+ L2: Episodic Memory [daily, ~800 tok] "What it means"│
155
+ │ ↓ synthesized into │
156
+ L3: Semantic Memory [cross-session] "What's true" │
157
+ (contradiction detection + goal evolution)
158
+ ├─────────────────────────────────────────────────────────┤
159
+ v3: JSON State Layer [per-session] Agent-to-agent data
160
+ │ journal_state .state.json alongside .md │
161
+ ├─────────────────────────────────────────────────────────┤
162
+ v3: Cache Layer HOT (0-1d) → WARM (2-7d) COLD │
163
+ │ journal_cold_start → loads 3 files, not 28 │
164
+ └─────────────────────────────────────────────────────────┘
193
165
  ```
194
166
 
195
167
  ---
@@ -200,35 +172,40 @@ Every session follows a structured quality cycle:
200
172
 
201
173
  ```
202
174
  🧠 THINK → Was the approach right? Was research done?
203
- ⚡ EXECUTE → What happened vs what was planned? (use COUNTS, not feelings)
204
- 🔍 REFLECT → 5-dimension quality score + Intelligent Distance gap analysis
175
+ ⚡ EXECUTE → What happened vs planned? (COUNTS, not feelings)
176
+ 🔍 REFLECT → 5-dimension quality score + Intelligent Distance gap
205
177
  🔄 FEEDBACK → Loop (needs iteration) or Exit (quality sufficient)
206
178
  ```
207
179
 
208
- **New in v2.1.1:** The Execute section requires COUNTS:
209
- > "Built 11 pages, 35 tabs, verified 82/91 routes return 200" — not "went well"
210
-
211
- **New in v2.1.1:** Failures section records what was ATTEMPTED and FAILED:
212
- > Not just successes. Failures are more valuable for learning.
180
+ **The Reflect step explicitly measures Intelligent Distance:**
181
+ - What user meant vs what I interpreted
182
+ - The gap between them (or "none — aligned")
183
+ - What to change so the gap shrinks next time
213
184
 
214
185
  ---
215
186
 
216
- ## Environment Variables
187
+ ## Supported Agents
217
188
 
218
- | Variable | Default | Description |
219
- |----------|---------|-------------|
220
- | `AGENT_RECALL_ROOT` | `~/.agent-recall` | Storage root directory |
221
- | `AGENT_RECALL_PROJECT` | (auto-detect) | Override project slug |
189
+ | Agent | Skill | MCP | Protocol |
190
+ |-------|:-----:|:---:|:--------:|
191
+ | Claude Code | | | |
192
+ | Cursor | | | |
193
+ | VS Code Copilot | — | ✅ | ✅ |
194
+ | Windsurf | ⚡ | ✅ | ✅ |
195
+ | Claude Desktop | — | ✅ | ✅ |
196
+ | Any MCP agent | — | ✅ | ✅ |
197
+ | Any AI agent | — | — | ✅ (manual) |
222
198
 
223
199
  ---
224
200
 
225
- ## CLI
201
+ ## Real Results
226
202
 
227
- ```bash
228
- npx agent-recall-mcp # Start MCP server (stdio)
229
- npx agent-recall-mcp --help # Show help
230
- npx agent-recall-mcp --list-tools # List all 12 tools as JSON
231
- ```
203
+ Validated over **30+ sessions** across 5 production projects:
204
+ - Cold-start: **5 min 2 seconds** (with v3 cache: loads 3 files not 28)
205
+ - Decision history: **0% → 100% retained** across sessions
206
+ - Misunderstanding caught before wrong work: **6+ instances** via alignment checks
207
+ - Quality loop caught **4 code review gaps** that would have shipped
208
+ - Failures section prevented **3 repeated mistakes** across agent handoffs
232
209
 
233
210
  ---
234
211
 
@@ -236,84 +213,19 @@ npx agent-recall-mcp --list-tools # List all 12 tools as JSON
236
213
 
237
214
  Built by [tongwu](https://github.com/Goldentrii) at [NovadaLabs](https://github.com/NovadaLabs).
238
215
 
239
- **We'd love your feedback.** If you're using AgentRecall, tell us what works and what doesn't:
216
+ **We'd love your feedback:**
240
217
 
241
218
  - Email: tongwu0824@gmail.com
242
219
  - GitHub Issues: [NovadaLabs/AgentRecall](https://github.com/NovadaLabs/AgentRecall/issues)
243
220
 
244
- ---
245
-
246
- ## License
247
-
248
- MIT
249
-
250
- ---
251
-
252
- ---
253
-
254
- # agent-recall-mcp(中文文档)
255
-
256
- > 给你的 AI 智能体一个跨会话记忆的大脑。
257
-
258
- MCP 服务器 — 双层会话记忆 + v3 JSON 状态层 + 缓存感知冷启动 + Think-Execute-Reflect 质量循环。兼容所有 MCP 客户端。
259
-
260
- **零云端。零遥测。所有数据保存在本地。**
261
-
262
- ---
263
-
264
- ## 快速开始
265
-
266
- ```bash
267
- # Claude Code
268
- claude mcp add agent-recall -- npx -y agent-recall-mcp
269
-
270
- # Cursor: .cursor/mcp.json
271
- { "mcpServers": { "agent-recall": { "command": "npx", "args": ["-y", "agent-recall-mcp"] } } }
272
- ```
221
+ 1. **Use the protocol** for a week → [report](https://github.com/NovadaLabs/AgentRecall/issues)
222
+ 2. **Implement it** in a new agent → PR welcome
223
+ 3. **Improve the spec** → [protocol doc](docs/intelligent-distance-protocol.md)
273
224
 
274
225
  ---
275
226
 
276
- ## 12 个工具
277
-
278
- ### 会话记忆(6 个)
279
-
280
- | 工具 | 功能 |
281
- |------|------|
282
- | `journal_read` | 按日期读取日志,支持章节过滤 |
283
- | `journal_write` | 追加或替换今日日志 |
284
- | `journal_capture` | 轻量问答捕获 |
285
- | `journal_list` | 列出最近日志 |
286
- | `journal_search` | 全文搜索 |
287
- | `journal_projects` | 列出所有项目 |
288
-
289
- ### v3 架构(3 个)— v2.1.1 新增
290
-
291
- | 工具 | 功能 |
292
- |------|------|
293
- | `journal_state` | **JSON 状态层** — 结构化读写,agent 间毫秒级交接 |
294
- | `journal_cold_start` | **缓存感知冷启动** — 热/温/冷三级,加载 3 个文件而非 28 个 |
295
- | `journal_archive` | **归档旧条目** — 移至 archive/,保留单行摘要 |
296
-
297
- ### 对齐 & 合成(3 个)
298
-
299
- | 工具 | 功能 |
300
- |------|------|
301
- | `alignment_check` | 记录理解度、置信度、人类纠正 |
302
- | `nudge` | 检测矛盾,主动提问 |
303
- | `context_synthesize` | 跨会话合成:目标演变、决策历史、模式检测 |
304
-
305
- ---
306
-
307
- ## 核心理念
308
-
309
- **记忆解决遗忘,AgentRecall 解决误解。**
310
-
311
- 人类和 AI 之间的理解差距是结构性的 — 人类说话前后矛盾、碎片化、含糊不清;AI 则以完美的自信构建错误的东西。AgentRecall 通过对齐检测、矛盾提醒和跨会话合成来弥合这个「智能距离」。
312
-
313
- ---
314
-
315
- ## 许可证
227
+ ## License
316
228
 
317
- MIT — [tongwu](https://github.com/Goldentrii) @ [NovadaLabs](https://github.com/NovadaLabs)
229
+ MIT — *Concept & Design: [tongwu](https://github.com/Goldentrii)*
318
230
 
319
- 反馈邮箱:tongwu0824@gmail.com
231
+ **Memory solves forgetting. AgentRecall solves misunderstanding.**
package/dist/index.js CHANGED
@@ -11,7 +11,7 @@ const execFileAsync = promisify(execFile);
11
11
  // ---------------------------------------------------------------------------
12
12
  // Constants
13
13
  // ---------------------------------------------------------------------------
14
- const VERSION = "3.2.0";
14
+ const VERSION = "3.2.2";
15
15
  const JOURNAL_ROOT = process.env.AGENT_RECALL_ROOT ||
16
16
  path.join(os.homedir(), ".agent-recall");
17
17
  const LEGACY_ROOT = path.join(os.homedir(), ".claude", "projects");
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agent-recall-mcp",
3
- "version": "3.2.0",
3
+ "version": "3.2.2",
4
4
  "description": "AI session memory with Think-Execute-Reflect quality loops — give your agent a brain that survives every session",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",