agent-recall-mcp 3.2.1 → 3.2.3

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 +216 -193
  2. package/dist/index.js +1 -1
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -1,222 +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>
19
-
20
- <p align="center"><strong>Zero cloud. Zero telemetry. All data stays on your machine.</strong></p>
21
-
22
15
  ---
23
16
 
24
- ## The Core Idea: Intelligent Distance
17
+ ## Intelligent Distance — The Core Idea
25
18
 
26
19
  > *"The gap between human intelligence and AI intelligence is structural and permanent — not a temporary technology problem."*
27
20
 
28
- Humans and AI think differently. Not better or worse — **differently**. Humans are born (embodied experience), machines are made (rules), AI is trained (statistical patterns). This gap — **Intelligent Distance** — means:
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.
29
22
 
30
- - When a human says "click all," the agent hears "click the main things"
31
- - When a human says "done means identical," the agent thinks "close enough"
32
- - When a human gives scattered instructions, the agent picks one and ignores the rest
23
+ **The conventional approach:** make AI more human-like → close the gap.
33
24
 
34
- **AgentRecall doesn't try to close this gap. It builds a protocol to navigate it.**
25
+ **The Intelligent Distance approach:** accept the gap as permanent → design a **protocol** that minimizes information loss when translating between the two intelligence types.
35
26
 
36
- Every tool in AgentRecall serves this purpose:
27
+ ```
28
+ Human says: "click all"
29
+ Agent hears: "click the main things"
30
+ Gap: "all" ≠ "main things"
37
31
 
38
- | Gap | Tool | How it helps |
39
- |-----|------|-------------|
40
- | Agent forgets what human said yesterday | `journal_read` + `journal_cold_start` | Persistent memory across sessions |
41
- | Agent misunderstands human intent | `alignment_check` | Records confidence + assumptions → human corrects before work starts |
42
- | Agent contradicts a prior decision | `nudge` | Detects contradiction → surfaces it before damage is done |
43
- | Agent says "done" but human disagrees | Think-Execute-Reflect loop | Structured quality scoring with COUNTS, not feelings |
44
- | Agent builds from imagination, not data | `journal_state` (JSON) | Transfers structured state agent-to-agent — no prose interpretation |
45
- | Agent repeats the same mistake | Failures section + `context_synthesize` | Patterns detected across sessions → promoted to permanent memory |
32
+ Human says: "done means identical"
33
+ Agent thinks: "close enough"
34
+ Gap: "identical" ≠ "close enough"
46
35
 
47
- **Memory solves forgetting. AgentRecall solves misunderstanding.**
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.**
48
42
 
49
43
  ---
50
44
 
51
- ## Why AgentRecall?
45
+ ## How AgentRecall Bridges the Gap
52
46
 
53
- | Problem | How AgentRecall Solves It |
54
- |---------|--------------------------|
55
- | Agent forgets everything between sessions | Three-layer memory persists state across sessions |
56
- | Agent repeats the same mistakes | Failures section + feedback promotion catches patterns |
57
- | Agent says "done" when it's not | Think-Execute-Reflect loop with quality scoring |
58
- | Cold start takes too long (28 journal files) | Cache-aware cold start: hot/warm/cold in <1 second |
59
- | Human has to explain context every time | JSON state layer transfers context agent-to-agent |
60
- | 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.**
61
58
 
62
59
  ---
63
60
 
64
61
  ## Quick Start
65
62
 
66
- ### Claude Code
63
+ ### MCP Server (any agent)
67
64
 
68
65
  ```bash
66
+ # Claude Code
69
67
  claude mcp add agent-recall -- npx -y agent-recall-mcp
70
- ```
71
68
 
72
- ### Cursor
73
-
74
- `.cursor/mcp.json`:
75
- ```json
76
- {
77
- "mcpServers": {
78
- "agent-recall": {
79
- "command": "npx",
80
- "args": ["-y", "agent-recall-mcp"]
81
- }
82
- }
83
- }
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"] } } }
84
74
  ```
85
75
 
86
- ### VS Code / Windsurf / Claude Desktop
76
+ ### Skill (Claude Code)
87
77
 
88
- 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.
89
85
 
90
86
  ---
91
87
 
92
- ## 12 Tools
88
+ ## 12 MCP Tools
93
89
 
94
90
  ### Session Memory (6 tools)
95
91
 
96
- | Tool | What it does |
97
- |------|-------------|
98
- | `journal_read` | Read entry by date or `"latest"`. Filter by section. |
99
- | `journal_write` | Append to or replace today's journal. |
100
- | `journal_capture` | Lightweight Q&A capture — one question + answer, tagged. |
101
- | `journal_list` | List recent entries (date, title, momentum). |
102
- | `journal_search` | Full-text search across all entries. |
103
- | `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 |
104
100
 
105
- ### v3 Architecture (3 tools) — NEW in v2.1.1
101
+ ### v3 Architecture (3 tools) — NEW
106
102
 
107
- | Tool | What it does |
108
- |------|-------------|
109
- | `journal_state` | **Layer 1 JSON state** — read/write structured session data. Agent-to-agent handoffs use JSON (milliseconds, no prose parsing). |
110
- | `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. |
111
- | `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 |
112
108
 
113
109
  ### Alignment & Synthesis (3 tools)
114
110
 
115
- | Tool | What it does |
116
- |------|-------------|
117
- | `alignment_check` | Record understanding, confidence, assumptions, and human corrections. |
118
- | `nudge` | Surface contradictions between current input and prior decisions. |
119
- | `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 |
120
116
 
121
117
  ---
122
118
 
123
- ## Architecture
119
+ ## How Alignment Detection Works
120
+
121
+ When an agent isn't sure it understands:
124
122
 
125
123
  ```
126
- ┌─────────────────────────────────────────────────────────────┐
127
- │ Agent Session │
128
- │ │
129
- │ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │
130
- │ │ L1: Working │ │ L2: Journal │ │ L3: Synthesis │ │
131
- │ │ Memory │ │ (daily) │ │ (cross-session) │ │
132
- │ │ ~50 tokens │ │ ~800 tokens │ │ ~200 tokens │ │
133
- │ │ │ │ │ │ │ │
134
- │ │ journal_ │ │ journal_ │ │ context_ │ │
135
- │ │ capture │ │ write/read │ │ synthesize │ │
136
- │ └──────┬───────┘ └──────┬───────┘ └────────┬─────────┘ │
137
- │ │ synthesized │ synthesized │ │
138
- │ └────────►─────────┘────────►───────────┘ │
139
- │ │
140
- │ ┌──────────────────────────────────────────────────────┐ │
141
- │ │ v3: JSON State Layer (agent-to-agent, no prose) │ │
142
- │ │ journal_state → .state.json alongside .md │ │
143
- │ └──────────────────────────────────────────────────────┘ │
144
- │ │
145
- │ ┌──────────────────────────────────────────────────────┐ │
146
- │ │ v3: Cache Layer (hot/warm/cold) │ │
147
- │ │ journal_cold_start → loads 3 files, not 28 │ │
148
- │ └──────────────────────────────────────────────────────┘ │
149
- └─────────────────────────────────────────────────────────────┘
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?
150
129
  ```
151
130
 
152
- ---
153
-
154
- ## Cache-Aware Cold Start (v3)
131
+ Human confirms or corrects. The delta is logged. Over time, patterns reveal where misunderstanding is most likely.
155
132
 
156
- ```
157
- ┌─ HOT (0-1 day) ─────────────────────────────────┐
158
- │ Full JSON state + brief from markdown │
159
- │ → Everything the next agent needs │
160
- └──────────────────────────────────────────────────┘
161
- ↓
162
- ┌─ WARM (2-7 days) ────────────────────────────────┐
163
- │ Brief summary only (first 2KB of journal) │
164
- │ → "What happened this week" context │
165
- └──────────────────────────────────────────────────┘
166
- ↓
167
- ┌─ COLD (7+ days) ─────────────────────────────────┐
168
- │ Count only. Use journal_read for full content. │
169
- │ Use journal_archive to move to archive/ folder. │
170
- └──────────────────────────────────────────────────┘
171
- ```
133
+ ## How Nudge Protocol Works
172
134
 
173
- ---
135
+ When the agent detects the human contradicts a prior decision:
174
136
 
175
- ## JSON State (v3) — Agent-to-Agent Format
176
-
177
- ```json
178
- {
179
- "version": "2.1.1",
180
- "date": "2026-04-07",
181
- "project": "my-project",
182
- "completed": [
183
- { "task": "built dashboard", "result": "11 pages, 35 tabs" }
184
- ],
185
- "failures": [
186
- { "task": "extraction", "what_went_wrong": "missed sub-tabs", "root_cause": "context fatigue", "fixed": true }
187
- ],
188
- "state": {
189
- "genome": { "status": "v3.2", "details": "8 dimensions" }
190
- },
191
- "next_actions": [
192
- { "priority": "P0", "task": "verify against real site" }
193
- ],
194
- "insights": [
195
- { "claim": "extraction quality = replication quality", "confidence": "high", "evidence": "4 sites tested" }
196
- ],
197
- "counts": { "pages": 91, "tabs": 35, "api_routes": 3 }
198
- }
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?
199
142
  ```
200
143
 
201
- 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.**
202
145
 
203
146
  ---
204
147
 
205
- ## Storage
148
+ ## Three-Layer Memory + v3 Cache
206
149
 
207
150
  ```
208
- ~/.agent-recall/
209
- └── projects/
210
- └── {project}/
211
- └── journal/
212
- ├── index.md ← auto-generated
213
- ├── 2026-04-07.md ← L2: daily journal (markdown)
214
- ├── 2026-04-07.state.json ← v3: structured state (JSON)
215
- ├── 2026-04-07-log.md ← L1: raw Q&A capture
216
- ├── 2026-04-07-alignment.md ← alignment checks
217
- └── archive/ ← v3: cold storage
218
- ├── index.md ← one-line summaries
219
- └── 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
+ └─────────────────────────────────────────────────────────┘
220
165
  ```
221
166
 
222
167
  ---
@@ -227,35 +172,40 @@ Every session follows a structured quality cycle:
227
172
 
228
173
  ```
229
174
  🧠 THINK → Was the approach right? Was research done?
230
- ⚡ EXECUTE → What happened vs what was planned? (use COUNTS, not feelings)
231
- 🔍 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
232
177
  🔄 FEEDBACK → Loop (needs iteration) or Exit (quality sufficient)
233
178
  ```
234
179
 
235
- **New in v2.1.1:** The Execute section requires COUNTS:
236
- > "Built 11 pages, 35 tabs, verified 82/91 routes return 200" — not "went well"
237
-
238
- **New in v2.1.1:** Failures section records what was ATTEMPTED and FAILED:
239
- > 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
240
184
 
241
185
  ---
242
186
 
243
- ## Environment Variables
187
+ ## Supported Agents
244
188
 
245
- | Variable | Default | Description |
246
- |----------|---------|-------------|
247
- | `AGENT_RECALL_ROOT` | `~/.agent-recall` | Storage root directory |
248
- | `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) |
249
198
 
250
199
  ---
251
200
 
252
- ## CLI
201
+ ## Real Results
253
202
 
254
- ```bash
255
- npx agent-recall-mcp # Start MCP server (stdio)
256
- npx agent-recall-mcp --help # Show help
257
- npx agent-recall-mcp --list-tools # List all 12 tools as JSON
258
- ```
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
259
209
 
260
210
  ---
261
211
 
@@ -263,16 +213,22 @@ npx agent-recall-mcp --list-tools # List all 12 tools as JSON
263
213
 
264
214
  Built by [tongwu](https://github.com/Goldentrii) at [NovadaLabs](https://github.com/NovadaLabs).
265
215
 
266
- **We'd love your feedback.** If you're using AgentRecall, tell us what works and what doesn't:
216
+ **We'd love your feedback:**
267
217
 
268
218
  - Email: tongwu0824@gmail.com
269
219
  - GitHub Issues: [NovadaLabs/AgentRecall](https://github.com/NovadaLabs/AgentRecall/issues)
270
220
 
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)
224
+
271
225
  ---
272
226
 
273
227
  ## License
274
228
 
275
- MIT
229
+ MIT — *Concept & Design: [tongwu](https://github.com/Goldentrii)*
230
+
231
+ **Memory solves forgetting. AgentRecall solves misunderstanding.**
276
232
 
277
233
  ---
278
234
 
@@ -282,9 +238,45 @@ MIT
282
238
 
283
239
  > 给你的 AI 智能体一个跨会话记忆的大脑。
284
240
 
285
- MCP 服务器 — 双层会话记忆 + v3 JSON 状态层 + 缓存感知冷启动 + Think-Execute-Reflect 质量循环。兼容所有 MCP 客户端。
241
+ ---
286
242
 
287
- **零云端。零遥测。所有数据保存在本地。**
243
+ ## 智能距离（Intelligent Distance）— 核心理念
244
+
245
+ > *「人类智能与 AI 智能之间的差距是结构性的、永久的 — 不是一个临时的技术问题。」*
246
+
247
+ 人类是「生出来的」（具身经验、情感、生存压力）。机器是「造出来的」（规则、确定性）。AI 是「训练出来的」（数据上的统计共现）。三种不同的认知起源，产生三种不同的理解方式。这个差距不会随 AI 进步而消失 — 因为差异在于**起源**，而非能力。
248
+
249
+ ```
250
+ 人类说：「全部点击」
251
+ AI 理解：「点击主要的」
252
+ 差距：「全部」≠「主要的」
253
+
254
+ 人类说：「做完意味着完全一样」
255
+ AI 认为：「差不多就行」
256
+ 差距：「完全一样」≠「差不多」
257
+
258
+ 人类给出：零散、非线性的指令
259
+ AI 选择：一条指令，忽略其余
260
+ 差距：点与点之间的逻辑关联丢失了
261
+ ```
262
+
263
+ **AgentRecall 不试图缩小这个差距，而是构建一个协议来导航它。**
264
+
265
+ ---
266
+
267
+ ## AgentRecall 如何弥合差距
268
+
269
+ | 智能距离缺口 | AgentRecall 工具 | 功能 |
270
+ |-------------|-----------------|------|
271
+ | 智能体忘了人类昨天说的话 | `journal_read` + `journal_cold_start` | 三层记忆 + 缓存感知冷启动 |
272
+ | 智能体误解人类意图 | `alignment_check` | 记录置信度 + 假设 → 人类在工作开始前纠正 |
273
+ | 智能体与之前的决策矛盾 | `nudge` | 检测矛盾 → 在造成损失前提出 |
274
+ | 智能体说「完成了」但人类不同意 | Think-Execute-Reflect 循环 | 用数字评分（「建了 11 页 35 个标签」），不用感觉（「做得不错」）|
275
+ | 智能体凭想象构建，而非基于数据 | `journal_state` (JSON) | agent 间结构化交接 — 毫秒级，无需解析散文 |
276
+ | 智能体重复同样的错误 | 失败记录 + `context_synthesize` | 跨会话模式检测 → 提升为永久记忆 |
277
+ | 下一个 agent 从零开始 | `journal_cold_start` (v3) | 热/温/冷缓存 — 加载 3 个文件而非 28 个 |
278
+
279
+ **记忆解决遗忘，AgentRecall 解决误解。**
288
280
 
289
281
  ---
290
282
 
@@ -294,8 +286,11 @@ MCP 服务器 — 双层会话记忆 + v3 JSON 状态层 + 缓存感知冷启动
294
286
  # Claude Code
295
287
  claude mcp add agent-recall -- npx -y agent-recall-mcp
296
288
 
297
- # Cursor: .cursor/mcp.json
289
+ # Cursor — .cursor/mcp.json
298
290
  { "mcpServers": { "agent-recall": { "command": "npx", "args": ["-y", "agent-recall-mcp"] } } }
291
+
292
+ # VS Code — .vscode/mcp.json
293
+ { "servers": { "agent-recall": { "command": "npx", "args": ["-y", "agent-recall-mcp"] } } }
299
294
  ```
300
295
 
301
296
  ---
@@ -313,42 +308,70 @@ claude mcp add agent-recall -- npx -y agent-recall-mcp
313
308
  | `journal_search` | 全文搜索 |
314
309
  | `journal_projects` | 列出所有项目 |
315
310
 
316
- ### v3 架构（3 个）— v2.1.1 新增
311
+ ### v3 架构（3 个）— 新增
317
312
 
318
313
  | 工具 | 功能 |
319
314
  |------|------|
320
315
  | `journal_state` | **JSON 状态层** — 结构化读写，agent 间毫秒级交接 |
321
- | `journal_cold_start` | **缓存感知冷启动** — 热/温/冷三级，加载 3 个文件而非 28 个 |
316
+ | `journal_cold_start` | **缓存感知冷启动** — 热（0-1天）/ 温（2-7天）/ 冷（7天+） |
322
317
  | `journal_archive` | **归档旧条目** — 移至 archive/，保留单行摘要 |
323
318
 
324
319
  ### 对齐 & 合成（3 个）
325
320
 
326
321
  | 工具 | 功能 |
327
322
  |------|------|
328
- | `alignment_check` | 记录理解度、置信度、人类纠正 |
323
+ | `alignment_check` | 记录理解度、置信度、假设、人类纠正 |
329
324
  | `nudge` | 检测矛盾，主动提问 |
330
325
  | `context_synthesize` | 跨会话合成：目标演变、决策历史、模式检测 |
331
326
 
332
327
  ---
333
328
 
334
- ## 核心理念：智能距离（Intelligent Distance）
329
+ ## 三层记忆 + v3 缓存
335
330
 
336
- > *「人类智能与 AI 智能之间的差距是结构性的、永久的 — 不是一个临时的技术问题。」*
331
+ ```
332
+ ┌─────────────────────────────────────────────────────────┐
333
+ │ L1: 工作记忆 [每轮, ~50 tok] 「发生了什么」 │
334
+ │ ↓ 合成为 │
335
+ │ L2: 情景记忆 [每日日志, ~800 tok] 「这意味着什么」 │
336
+ │ ↓ 合成为 │
337
+ │ L3: 语义记忆 [跨会话] 「跨会话的真相」 │
338
+ │ （矛盾检测 + 目标演变追踪） │
339
+ ├─────────────────────────────────────────────────────────┤
340
+ │ v3: JSON 状态层 [每会话] agent 间结构化数据 │
341
+ ├─────────────────────────────────────────────────────────┤
342
+ │ v3: 缓存层 热（0-1天）→ 温（2-7天）→ 冷（7天+） │
343
+ │ journal_cold_start → 加载 3 个文件而非 28 个 │
344
+ └─────────────────────────────────────────────────────────┘
345
+ ```
337
346
 
338
- 人类是「生出来的」（具身经验）、机器是「造出来的」（规则驱动）、AI 是「训练出来的」（统计共现）。三种不同的认知基底，产生三种不同的理解方式。这个差距就是**智能距离**。
347
+ ---
339
348
 
340
- AgentRecall 不试图缩小这个差距，而是构建一个**协议**来最小化信息损失：
341
- - `alignment_check` — 在开始工作前记录理解和假设，让人类纠正
342
- - `nudge` — 检测到矛盾时主动提问，而不是默默构建错误的东西
343
- - Think-Execute-Reflect — 用数字而非感觉评估质量（「建了 11 页 35 个标签」而非「做得不错」）
344
- - `journal_state` (JSON) — agent 间用结构化数据交接，不靠散文解析
349
+ ## Think-Execute-Reflect 质量循环
345
350
 
346
- **记忆解决遗忘，AgentRecall 解决误解。**
351
+ ```
352
+ 🧠 THINK → 方法对吗？做了调研吗？
353
+ ⚡ EXECUTE → 实际 vs 计划？（用数字，不用感觉）
354
+ 🔍 REFLECT → 5 维度质量评分 + 智能距离差距分析
355
+ 🔄 FEEDBACK → 循环（需要迭代）或 退出（质量足够）
356
+ ```
357
+
358
+ **Reflect 步骤显式测量智能距离：**
359
+ - 用户意图 vs 我的理解
360
+ - 两者之间的差距（或「无 — 已对齐」）
361
+ - 下次如何缩小差距
362
+
363
+ ---
364
+
365
+ ## 反馈 & 贡献
366
+
367
+ 由 [tongwu](https://github.com/Goldentrii) 在 [NovadaLabs](https://github.com/NovadaLabs) 构建。
368
+
369
+ **我们期待你的反馈：**
370
+ - 邮箱：tongwu0824@gmail.com
371
+ - GitHub Issues：[NovadaLabs/AgentRecall](https://github.com/NovadaLabs/AgentRecall/issues)
347
372
 
348
373
  ---
349
374
 
350
375
  ## 许可证
351
376
 
352
377
  MIT — [tongwu](https://github.com/Goldentrii) @ [NovadaLabs](https://github.com/NovadaLabs)
353
-
354
- 反馈邮箱：tongwu0824@gmail.com
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.1";
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.1",
3
+ "version": "3.2.3",
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",