agent-recall-sdk 3.3.28 → 3.4.0

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 (2) hide show
  1. package/README.md +427 -582
  2. package/package.json +2 -2
package/README.md CHANGED
@@ -9,24 +9,26 @@
9
9
  <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>
10
10
  <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>
11
11
  <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>
12
- <img src="https://img.shields.io/badge/MCP-5_tools-orange?style=flat-square" alt="Tools">
12
+ <a href="https://lobehub.com/mcp/goldentrii-agentrecall"><img src="https://lobehub.com/badge/mcp/goldentrii-agentrecall" alt="MCP Badge"></a>
13
+ <img src="https://img.shields.io/badge/MCP-10_tools-orange?style=flat-square" alt="Tools">
13
14
  <img src="https://img.shields.io/badge/cloud-zero-blue?style=flat-square" alt="Zero Cloud">
14
15
  <img src="https://img.shields.io/badge/Obsidian-compatible-7C3AED?style=flat-square" alt="Obsidian">
15
- <img src="https://img.shields.io/badge/overhead-~876_tokens%2Fsession-22C55E?style=flat-square" alt="Token overhead">
16
+ <img src="https://img.shields.io/badge/digest_cache-83%25_token_savings-FF6B6B?style=flat-square" alt="Digest cache savings">
16
17
  <img src="https://img.shields.io/badge/saves_up_to-57%25_tokens-FF6B6B?style=flat-square" alt="Token savings">
17
18
  <img src="https://img.shields.io/badge/break--even-3--4_sessions-22C55E?style=flat-square" alt="Break-even">
18
19
  <img src="https://img.shields.io/badge/scoring-RRF_(Cormack_2009)-7C3AED?style=flat-square" alt="RRF scoring">
19
- <img src="https://img.shields.io/badge/decay-Ebbinghaus_(1885)-3B82F6?style=flat-square" alt="Ebbinghaus decay">
20
- <img src="https://img.shields.io/badge/feedback-Bayesian_Beta-F59E0B?style=flat-square" alt="Beta distribution">
20
+ <img src="https://img.shields.io/badge/decay-Ebbinghaus%2BZipf-3B82F6?style=flat-square" alt="Ebbinghaus+Zipf decay">
21
+ <img src="https://img.shields.io/badge/feedback-Bayesian_Beta_(active)-F59E0B?style=flat-square" alt="Beta distribution">
22
+ <img src="https://img.shields.io/badge/semantic_recall-pgvector_%2B_RRF-8B5CF6?style=flat-square" alt="Semantic recall">
21
23
  </p>
22
24
 
23
25
  <p align="center">
24
26
  <b>EN:</b>&nbsp;
25
27
  <a href="#why-choose-agentrecall">Why</a> ·
26
28
  <a href="#three-ways-to-use-it">Use</a> ·
27
- <a href="#what-is-agentrecall">What</a> ·
28
29
  <a href="#quick-start">Install</a> ·
29
- <a href="#5-mcp-tools">Tools</a> ·
30
+ <a href="#semantic-recall--pgvector-backend-v340">Semantic Recall</a> ·
31
+ <a href="#10-mcp-tools">Tools</a> ·
30
32
  <a href="#how-memory-compounds">Compounding</a> ·
31
33
  <a href="#sdk-api">SDK</a> ·
32
34
  <a href="#architecture">Architecture</a> ·
@@ -35,17 +37,20 @@
35
37
  <b>中文:</b>&nbsp;
36
38
  <a href="#agentrecall中文文档">简介</a> ·
37
39
  <a href="#快速开始">安装</a> ·
38
- <a href="#5-个-mcp-工具">工具</a> ·
40
+ <a href="#语义召回--pgvector-v340">语义召回</a> ·
41
+ <a href="#10-个-mcp-工具">工具</a> ·
39
42
  <a href="#记忆如何复合增长">复合</a> ·
40
- <a href="#sdk-api-1">SDK</a> ·
41
43
  <a href="#架构">架构</a>
42
44
  </p>
43
45
 
44
46
  ---
45
47
 
46
48
  <p align="center">
47
- <a href="#arsave-and-arstart"><img src="https://img.shields.io/badge/%2Farsave-Save_Session-FF6B6B?style=for-the-badge" alt="/arsave"></a>
48
- <a href="#arsave-and-arstart"><img src="https://img.shields.io/badge/%2Farstart-Load_Context-4ECDC4?style=for-the-badge" alt="/arstart"></a>
49
+ <a href="#arstatus-arsave-arstart-arsaveall-and-arbootstrap"><img src="https://img.shields.io/badge/%2Farstatus-START_HERE-22C55E?style=for-the-badge" alt="/arstatus"></a>
50
+ <a href="#arstatus-arsave-arstart-arsaveall-and-arbootstrap"><img src="https://img.shields.io/badge/%2Farstart-Load_Context-4ECDC4?style=for-the-badge" alt="/arstart"></a>
51
+ <a href="#arstatus-arsave-arstart-arsaveall-and-arbootstrap"><img src="https://img.shields.io/badge/%2Farsave-Save_Session-FF6B6B?style=for-the-badge" alt="/arsave"></a>
52
+ <a href="#arstatus-arsave-arstart-arsaveall-and-arbootstrap"><img src="https://img.shields.io/badge/%2Farsaveall-Batch_Save_All-FFD93D?style=for-the-badge" alt="/arsaveall"></a>
53
+ <a href="#already-using-another-memory-system-arbootstrap"><img src="https://img.shields.io/badge/%2Farbootstrap-Transfer_Memory-8B5CF6?style=for-the-badge" alt="/arbootstrap"></a>
49
54
  </p>
50
55
  <p align="center">
51
56
  <img src="https://img.shields.io/badge/AUTO-hook--start-8B5CF6?style=for-the-badge" alt="hook-start">
@@ -60,22 +65,205 @@
60
65
  <a href="#how-memory-compounds"><img src="https://img.shields.io/badge/5-FEEDBACK_LOOP-EF4444?style=for-the-badge" alt="Feedback Loop"></a>
61
66
  </p>
62
67
 
63
- ## `/arsave` and `/arstart`
68
+ ## Already Using Another Memory System? `/arbootstrap`
64
69
 
65
- > **Two commands. That's all you need.**
70
+ > [!NOTE]
71
+ > **You don't start from zero.** If you've been using Claude's built-in memory, Mem0, or just working in git repos — AgentRecall can discover and import your existing context automatically.
72
+
73
+ Most users installing AgentRecall aren't starting fresh. They already have:
74
+ - **Git repos** with months of commit history and project structure
75
+ - **Claude AutoMemory** (`~/.claude/projects/`) with user profiles, feedback, and project memories
76
+ - **CLAUDE.md files** with project conventions and architecture decisions
77
+
78
+ **`/arbootstrap`** scans your machine and imports everything in one shot:
79
+
80
+ ```
81
+ /arbootstrap
82
+
83
+ ──────────────────────────────────────────────────────────────
84
+ AgentRecall Bootstrap Scan 2026-04-26
85
+ ──────────────────────────────────────────────────────────────
86
+
87
+ Found on your machine:
88
+ 24 git repos
89
+ 92 Claude memory files
90
+ 3 CLAUDE.md files
91
+
92
+ Projects:
93
+ 18 new (not yet in AgentRecall)
94
+ 10 already imported
95
+
96
+ Scan time: 141ms
97
+ ──────────────────────────────────────────────────────────────
98
+ ```
99
+
100
+ **What gets imported per project:**
101
+ - **Identity** — project name, language, description → `palace/identity.md`
102
+ - **Architecture** — CLAUDE.md conventions → `palace/rooms/architecture/`
103
+ - **Memory** — Claude AutoMemory files → `palace/rooms/knowledge/`
104
+ - **Trajectory** — recent git history → initial journal entry
105
+
106
+ **Safety guarantees:**
107
+ - Scan is read-only — never writes to your machine
108
+ - Import only writes to `~/.agent-recall/` — never modifies source files
109
+ - Skips `.env`, credentials, `.pem`, `.key` — never reads secrets
110
+ - Projects already in AgentRecall are skipped (no double-import)
111
+
112
+ **For MCP-only environments** (Codex, Cursor, VS Code Copilot):
113
+ ```
114
+ bootstrap_scan() # discover what's on the machine
115
+ bootstrap_import({ scan_result }) # import selected projects
116
+ ```
117
+
118
+ **For CLI:**
119
+ ```bash
120
+ ar bootstrap # scan and show results
121
+ ar bootstrap --dry-run # preview what would be imported
122
+ ar bootstrap --import # import all new projects
123
+ ar bootstrap --import --project X # import one project
124
+ ```
125
+
126
+ After bootstrap, run `/arstatus` — your projects are ready.
127
+
128
+ ---
129
+
130
+ ## `/arstatus`, `/arsave`, `/arstart`, `/arsaveall`, and `/arbootstrap`
131
+
132
+ > [!TIP]
133
+ > **New to AgentRecall?** Read the **[→ Command Reference](docs/commands.md)** — full instructions, all example outputs, installation, and troubleshooting in one place.
134
+
135
+ > [!IMPORTANT]
136
+ > **Run `/arstatus` at the start of every session.** It shows all your projects, what's pending, what's blocked, and lets you pick what to work on — by number, not by remembering project names. Without it, a fresh agent has no idea where to begin.
66
137
 
67
138
  | Command | When | What it does |
68
139
  |---------|------|-------------|
69
- | **`/arsave`** | End of session | Write journal + consolidate to palace + update awareness + optional git push |
70
- | **`/arstart`** | Start of session | Recall cross-project insights + walk palace + load context |
140
+ | ⭐ **`/arstatus`** | **Every session — run this first** | **Status board across ALL projects: pending work, blockers, numbered pick list. The true cold start.** |
141
+ | **`/arstart`** | After picking a project | Load deep context for one project: palace rooms, corrections, task-specific recall |
142
+ | **`/arsave`** | End of session | Write journal + consolidate to palace + update awareness |
143
+ | **`/arsaveall`** | End of day (multi-session) | **Batch save all parallel sessions at once** — scan, merge, deduplicate, done |
144
+ | **`/arbootstrap`** | **First install / switching from another memory system** | **Scan your machine for existing projects and import them into AgentRecall in seconds** |
145
+
146
+ **The session flow:** `/arstatus` → pick a number → `/arstart <project>` → work → `/arsave`.
147
+
148
+ **Running 5 agents in parallel?** Don't `/arsave` five times. Type **`/arsaveall`** once — it scans all of today's sessions across all projects, merges them into consolidated journals, deduplicates insights, and updates awareness in one shot. Each session writes to its own file (session-ID scoped), so **no conflicts, no data loss, no matter how many windows you have open.**
149
+
150
+ ### What You'll See
151
+
152
+ Type `/arstatus` → see everything in flight across all projects, pick by number:
153
+
154
+ ```
155
+ ──────────────────────────────────────────────────────────────
156
+ AgentRecall Status Board 2026-04-21 5 projects
157
+ ──────────────────────────────────────────────────────────────
158
+
159
+ 1 ⚠ novada-site 2026-04-21 BLOCKED
160
+ Blocked: .env.local missing — Phase 1 cannot proceed
161
+
162
+ 2 ● novada-mcp 2026-04-21
163
+ Next: fix novada_search POST /request → publish v0.8.0
164
+
165
+ 3 ● prismma-scraper 2026-04-17
166
+ Next: UI upgrade Option A — light mode + 3D visuals
167
+
168
+ 4 ✓ AgentRecall 2026-04-21 complete
169
+ Collecting real production data
170
+
171
+ ──────────────────────────────────────────────────────────────
172
+ Enter a number, or:
173
+ N New project (with memory — agent knows your full history)
174
+ X New project (clean slate — no prior context, pure objectivity)
175
+ ──────────────────────────────────────────────────────────────
176
+ ```
177
+
178
+ Type `/arsave` → the system saves everything and renders a card with exact file paths and counts:
179
+
180
+ ```
181
+ ──────────────────────────────────────────────────────────────
182
+ AgentRecall ✓ Saved my-project 2026-04-20 #12
183
+ ──────────────────────────────────────────────────────────────
184
+
185
+ Journal ~/.agent-recall/projects/my-project/journal/
186
+ └─ 2026-04-20--arsave--15L--review-feedback.md [written]
187
+
188
+ Awareness 2 insights added (8 total)
189
+
190
+ Palace ~/.agent-recall/projects/my-project/palace/
191
+ ├─ rooms/Architecture [updated]
192
+ └─ rooms/Goals [updated]
193
+
194
+ Corrections 3 stored (always loaded at session start)
71
195
 
72
- Type `/arsave` after a long project session. Everything gets saved. Type `/arstart` next time. Everything loads back.
196
+ ⚡ Similar entries found — consider merging:
197
+ 2026-04-19 (review, feedback, architecture)
198
+
199
+ ──────────────────────────────────────────────────────────────
200
+ ```
201
+
202
+ Type `/arstart` → loads all context from memory in one shot:
203
+
204
+ ```
205
+ ──────────────────────────────────────────────────────────────
206
+ AgentRecall ↻ Loaded my-project 2026-04-21
207
+ ──────────────────────────────────────────────────────────────
208
+
209
+ Project my-project — SaaS platform for AI agents
210
+ Last session 2026-04-20 — review + feedback loop shipped
211
+
212
+ Insights (top 3):
213
+ [5×] Server-rendered cards beat agent templates
214
+ [3×] Per-message dedup beats per-session dedup
215
+ [2×] Stemming + synonyms improve keyword recall
216
+
217
+ ⚠ Past corrections — watch out:
218
+ - "No dark backgrounds" (corrected 3×)
219
+ - "Use bb-browser, not Playwright" (corrected 2×)
220
+
221
+ Cross-project: 2 related insights from novada-mcp
222
+
223
+ ──────────────────────────────────────────────────────────────
224
+ ```
225
+
226
+ Type `/arsaveall` → batch-saves all parallel sessions at once:
227
+
228
+ ```
229
+ ──────────────────────────────────────────────────────────────
230
+ AgentRecall ✓ Batch Saved 2026-04-20
231
+ ──────────────────────────────────────────────────────────────
232
+
233
+ Sessions scanned 5
234
+ Projects saved my-project, novada-mcp, prismma-scraper
235
+ Insights merged 4 (deduplicated from 7)
236
+ Corrections 2 new (auto-captured via hooks)
237
+
238
+ ──────────────────────────────────────────────────────────────
239
+ ```
240
+
241
+ Type `/arbootstrap` → discover and import projects from your existing tools:
242
+
243
+ ```
244
+ ──────────────────────────────────────────────────────────────
245
+ AgentRecall Bootstrap Complete 2026-04-26
246
+ ──────────────────────────────────────────────────────────────
247
+
248
+ 12 projects created
249
+ 87 items imported (identity, memory, architecture, trajectory)
250
+ 3 items skipped
251
+ 0 errors
252
+
253
+ Run /arstatus to see your projects.
254
+ ──────────────────────────────────────────────────────────────
255
+ ```
256
+
257
+ The cards are **rendered server-side** — computed from actual operation results, not agent interpretation. What you see is always accurate.
73
258
 
74
259
  ```bash
75
260
  # Install commands (one-time, Claude Code only)
76
261
  mkdir -p ~/.claude/commands
77
- curl -o ~/.claude/commands/arsave.md https://raw.githubusercontent.com/Goldentrii/AgentRecall/main/commands/arsave.md
262
+ curl -o ~/.claude/commands/arstatus.md https://raw.githubusercontent.com/Goldentrii/AgentRecall/main/commands/arstatus.md
78
263
  curl -o ~/.claude/commands/arstart.md https://raw.githubusercontent.com/Goldentrii/AgentRecall/main/commands/arstart.md
264
+ curl -o ~/.claude/commands/arsave.md https://raw.githubusercontent.com/Goldentrii/AgentRecall/main/commands/arsave.md
265
+ curl -o ~/.claude/commands/arsaveall.md https://raw.githubusercontent.com/Goldentrii/AgentRecall/main/commands/arsaveall.md
266
+ curl -o ~/.claude/commands/arbootstrap.md https://raw.githubusercontent.com/Goldentrii/AgentRecall/main/commands/arbootstrap.md
79
267
  ```
80
268
 
81
269
  ### The Difference
@@ -92,6 +280,19 @@ Day 2: "What monorepo?" Day 2: /arstart
92
280
  → Misses half the tasks → Pushes to both repos
93
281
  ```
94
282
 
283
+ ```
284
+ WITHOUT AgentRecall (5 parallel agents) WITH AgentRecall (5 parallel agents)
285
+ ────────────────────────────────────── ────────────────────────────────────
286
+
287
+ Agent 1 finishes: you /arsave Agent 1-5 finish: you type /arsaveall once
288
+ Agent 2 finishes: you /arsave again → Scans all 5 sessions automatically
289
+ Agent 3 finishes: you /arsave again → Merges into consolidated journals
290
+ Agent 4 finishes: you /arsave again → Deduplicates insights across sessions
291
+ Agent 5 finishes: you /arsave again → Zero conflicts (session-ID scoped files)
292
+ → 5x the work, corrections lost → One command, everything saved
293
+ → Agent 3's correction unknown to Agent 5 → All agents share the same memory
294
+ ```
295
+
95
296
  ### Three Layers of Value
96
297
 
97
298
  **Layer 1 (5 seconds):** It makes your AI agent remember what happened last session.
@@ -100,47 +301,6 @@ Day 2: "What monorepo?" Day 2: /arstart
100
301
 
101
302
  **Layer 3 (2 minutes):** The [Intelligent Distance Protocol](https://github.com/Goldentrii/AgentRecall/wiki/Intelligent-Distance). The structural gap between human thinking and AI action can't be closed — but it can be navigated better every session. Corrections are training data. The 200-line awareness cap forces quality over quantity. Cross-project insights mean lessons learned once apply everywhere.
102
303
 
103
- ### Real Session Flow
104
-
105
- This is from an actual multi-day project where a human gave scattered, non-linear instructions. The agent used AgentRecall throughout:
106
-
107
- ```
108
- Session 1 (Tuesday) Session 2 (Wednesday, different agent)
109
- ───────────────── ─────────────────────────────────────
110
-
111
- /arstart /arstart
112
- │ │
113
- ├─ session_start() ──→ identity, ├─ session_start() ──→ loads Tuesday's
114
- │ top insights, active rooms, │ decisions in ~400 tokens,
115
- │ cross-project matches, │ watch_for: "structurize input"
116
- │ watch_for warnings │
117
- │ ├─ recall("SDK CLI monorepo") ──→
118
- ├─ recall("SDK CLI versions") ──→ │ • "no version inflation"
119
- │ • "structurize scattered input" │ • "arsave/arstart = hero section"
120
- │ • "search before building" │
121
- │ • "ask when ambiguous" ├─ Continues exactly where
122
- │ │ Session 1 left off
123
- ▼ │
124
- Human: "we need SDK, CLI, ▼
125
- update README, fix versions" Human: "publish to npm,
126
- │ update both GitHub repos"
127
- ├─ check(goal="SDK+CLI+README", │
128
- │ confidence="medium") ├─ No re-explanation needed.
129
- │ → 4 tasks detected │ Agent already knows the
130
- │ → present plan → human confirms │ monorepo structure, package
131
- │ │ names, and version policy.
132
- ├─ Execute in order: │
133
- │ 1. Core extraction ✓ └─ Done in 2 minutes
134
- │ 2. Tool logic split ✓ (vs 20 min cold start
135
- │ 3. MCP wrappers ✓ without AgentRecall)
136
- │ 4. SDK + CLI ✓
137
- │
138
- /arsave
139
- │
140
- └─ session_end(summary, insights, trajectory)
141
- → journal + awareness + palace — one call
142
- ```
143
-
144
304
  ---
145
305
 
146
306
  ## Why Choose AgentRecall
@@ -149,8 +309,6 @@ Human: "we need SDK, CLI, ▼
149
309
 
150
310
  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: your priorities, your communication style, your non-negotiables.
151
311
 
152
- This is the **Intelligent Distance Protocol** — not closing the gap between human and AI (that gap is structural), but navigating it better every session.
153
-
154
312
  - **Your agent learns how you think.** Humans are inconsistent — we skip from A to E, forget what we said yesterday, change priorities mid-sentence. AgentRecall captures every correction and surfaces it before the next mistake. The gap between what you mean and what your agent does shrinks with every session.
155
313
 
156
314
  - **Compounding awareness, not infinite logs.** Memory is capped at 200 lines. New insights either merge with existing ones (strengthening them) or replace the weakest. After 100 sessions, your awareness file is still 200 lines — but each line carries the weight of cross-validated, confirmed observations.
@@ -161,44 +319,6 @@ This is the **Intelligent Distance Protocol** — not closing the gap between hu
161
319
 
162
320
  - **Zero cloud, zero telemetry, all local.** Everything is markdown on disk. Browse it in Obsidian, grep it in the terminal, version it in git. No accounts, no API keys, no lock-in.
163
321
 
164
- ### Use Case 1: The Scattered Human
165
-
166
- A real session where the human gave non-linear, scattered instructions across a 2-day project:
167
-
168
- > Human: "we need SDK, CLI, also update README, oh and the npm versions are wrong, fix those too"
169
-
170
- Without AgentRecall, the agent guesses priority and misses items. With AgentRecall:
171
-
172
- | What the agent already knew | How it knew |
173
- |---|---|
174
- | "This human communicates in scattered bursts — structurize into modules before executing" | `awareness_update` from 3 prior sessions |
175
- | "Ask when ambiguous, proceed when clear" | `alignment_check` correction stored last week |
176
- | "No version inflation — this human cares about semver discipline" | `nudge` captured mid-session, recalled immediately |
177
-
178
- Result: Agent presented a structured 4-step plan, human confirmed, zero rework. A fresh agent without AgentRecall would have guessed wrong on versions, buried the most important feature in the README, and published without testing.
179
-
180
- ### Use Case 2: The Cross-Project Lesson
181
-
182
- An engineer built a proxy server with rate limiting (Project A). Three weeks later, started an API gateway (Project B).
183
-
184
- ```
185
- /arstart on Project B:
186
- recall_insight: "Rate limiting prevents runaway costs"
187
- → source: Project A, confirmed 3x, severity: critical
188
- → applies_when: ["api", "proxy", "rate-limit", "cost"]
189
- → The lesson from Project A surfaces automatically in Project B
190
- ```
191
-
192
- The engineer never mentioned rate limiting. AgentRecall matched the project context against the global insights index and surfaced it proactively.
193
-
194
- ### Use Case 3: The Correction That Sticks
195
-
196
- Session 1: Agent uses version 4.0.0 for a patch release. Human corrects: "That's version inflation. Use 3.3.4."
197
-
198
- Session 2 (next day, different agent): Awareness already contains "no version inflation — this human cares about conservative versioning." The new agent gets it right the first time.
199
-
200
- Without AgentRecall, the same correction would be needed again. And again. And again. With AgentRecall, **every correction happens exactly once.**
201
-
202
322
  ---
203
323
 
204
324
  ## Three Ways to Use It
@@ -227,10 +347,6 @@ npx agent-recall-cli palace walk --depth active
227
347
 
228
348
  A **learning system** that bridges the gap between how humans think and how AI agents work. Not a log. Not a database. A compounding loop where every correction, decision, and insight makes the next session better than the last.
229
349
 
230
- **The problem:** AI agents don't truly forget — they lose focus. Priorities blur across sessions. Lessons go dormant. The same misunderstanding happens twice because no one stored the correction. The gap between what you mean and what your agent does stays constant, session after session.
231
-
232
- **The fix:** AgentRecall stores knowledge in a five-layer memory pyramid — from quick captures to cross-project insights — and forces compression so memory gets more valuable over time. But more importantly, it closes the **Intelligent Distance** gap: every human correction is captured, weighted, and recalled before the agent makes the same mistake again.
233
-
234
350
  | Without AgentRecall | With AgentRecall |
235
351
  |---------------------|------------------|
236
352
  | Agent forgets yesterday's decisions | Decisions live in palace rooms, loaded on cold start |
@@ -278,55 +394,71 @@ npm install agent-recall-sdk
278
394
 
279
395
  ```typescript
280
396
  import { AgentRecall } from "agent-recall-sdk";
281
-
282
397
  const memory = new AgentRecall({ project: "my-app" });
283
-
284
- // Capture knowledge
285
- await memory.capture("What ORM?", "Drizzle — type-safe, lightweight");
286
-
287
- // Write to memory palace
288
- await memory.palaceWrite("architecture", "Stack: Next.js 16 + Drizzle + Postgres");
289
-
290
- // Cold start — load project context in ~200 tokens
291
- const context = await memory.coldStart();
292
-
293
- // Recall cross-project insights
294
- const insights = await memory.recallInsight("rate limiting");
295
-
296
- // Walk the palace at different depths
297
- const walk = await memory.walk("active");
398
+ await memory.coldStart(); // load context (~200 tokens)
399
+ await memory.capture("Q", "A"); // quick capture
400
+ await memory.palaceWrite("architecture", "Stack: Next.js + Drizzle");
298
401
  ```
299
402
 
300
403
  ### CLI (for terminal and CI)
301
404
 
302
405
  ```bash
303
406
  npm install -g agent-recall-cli
304
- # or use npx: npx agent-recall-cli <command>
407
+ ar capture "What ORM?" "Drizzle" --project my-app
408
+ ar palace walk --depth active
409
+ ar search "rate limiting" --include-palace
305
410
  ```
306
411
 
412
+ ---
413
+
414
+ ## Semantic Recall — pgvector Backend (v3.4.0)
415
+
416
+ > [!NOTE]
417
+ > **New in v3.4.0.** Default keyword recall works without any configuration. Upgrade to Supabase + pgvector when keyword search hits its ceiling: synonyms, paraphrased queries, multi-language recall.
418
+
419
+ Keyword search matches tokens. Semantic search matches **meaning**. After upgrading:
420
+ - `recall("session expiry")` also surfaces entries about "token refresh" and "auth timeout"
421
+ - No hand-crafted synonyms needed — embeddings handle the gap
422
+ - Local files remain the source of truth — Supabase is a derived read index
423
+
424
+ ### Setup (3 steps)
425
+
307
426
  ```bash
308
- # Capture a Q&A pair
309
- ar capture "What ORM?" "Drizzle" --project my-app
427
+ # Step 1 — interactive setup wizard
428
+ ar setup supabase
310
429
 
311
- # Read today's journal
312
- ar read --date latest
430
+ # Step 2 — apply pgvector migration to your Supabase project
431
+ ar setup supabase --migrate
313
432
 
314
- # Walk the memory palace
315
- ar palace walk --depth active
433
+ # Step 3 — done. Run /arstart — backfill happens automatically.
434
+ ```
316
435
 
317
- # Search across all memory
318
- ar search "rate limiting" --include-palace
436
+ The wizard prompts for your Supabase project URL and service role key → writes to `~/.agent-recall/config.json`. Never committed to git.
319
437
 
320
- # Recall cross-project insights
321
- ar insight "building auth middleware"
438
+ ### How it works
322
439
 
323
- # Write to a palace room
324
- ar palace write architecture "Switched from REST to tRPC"
440
+ ```
441
+ remember() / session_end()
442
+ → writes to local ~/.agent-recall/ as always ← source of truth, unchanged
443
+ → async: syncs to Supabase memories table
444
+ → OpenAI text-embedding-3-small (1536 dims)
445
+ or Voyage voyage-3-lite (512 dims, zero-padded to 1536)
446
+ → pgvector stores the embedding
325
447
 
326
- # Compact old journals into weekly summaries
327
- ar rollup --min-age-days 14
448
+ recall(query)
449
+ → Supabase configured?
450
+ YES → cosine similarity search via pgvector, reranked with local RRF
451
+ NO → local keyword search (existing behavior, unchanged)
328
452
  ```
329
453
 
454
+ ### Graceful degradation
455
+
456
+ If Supabase is unreachable (network error, quota exceeded, not configured), `recall()` falls back to local keyword search silently. Zero behavior change if the feature is never configured.
457
+
458
+ **Required:** `SUPABASE_URL` + `SUPABASE_SERVICE_ROLE_KEY` + either `OPENAI_API_KEY` or `VOYAGE_API_KEY`. All optional — AgentRecall works fully without them.
459
+
460
+ **Rebuild index:** `ar setup supabase --backfill` — re-embeds all local memories into Supabase.
461
+
330
462
  ---
331
463
 
332
464
  ## How an Agent Uses AgentRecall
@@ -352,7 +484,7 @@ Wire once in `~/.claude/settings.json`. Every session is captured automatically,
352
484
  ```
353
485
 
354
486
  - **hook-start** — on every session open: prints identity + top insights + watch_for warnings
355
- - **hook-correction** — on every prompt: detects corrections (regex) and captures them silently
487
+ - **hook-correction** — on every prompt: detects corrections (regex) and captures them silently
356
488
  - **hook-end** — on every session close: appends a lightweight end-of-session log entry
357
489
 
358
490
  ### Session Start (`/arstart`)
@@ -376,9 +508,9 @@ session_end(summary="...", insights=[...], trajectory="...") → journal + awar
376
508
 
377
509
  ---
378
510
 
379
- ## 5 MCP Tools
511
+ ## 10 MCP Tools
380
512
 
381
- AgentRecall exposes exactly 5 tools to agents. Each tool composes multiple subsystems internally — the agent doesn't need to know about the plumbing.
513
+ AgentRecall exposes 10 tools to agents. Each tool composes multiple subsystems internally — the agent doesn't need to know about the plumbing.
382
514
 
383
515
  | Tool | What it does |
384
516
  |------|-------------|
@@ -387,6 +519,11 @@ AgentRecall exposes exactly 5 tools to agents. Each tool composes multiple subsy
387
519
  | `recall` | Search all memory stores at once using **Reciprocal Rank Fusion (RRF)** — each source ranks internally, then positions are merged so no source dominates by default. Returns ranked results with stable IDs. Accepts `feedback` to rate previous results: positive boosts future ranking, negative penalizes. Query-aware — feedback from one search doesn't bleed into unrelated queries. |
388
520
  | `session_end` | Save everything in one call. Writes journal, updates awareness with new insights, consolidates to palace rooms, archives demoted insights (not deleted — preserved with resurrection support). |
389
521
  | `check` | Record what you think the human wants. Returns `watch_for` patterns from past correction history ("You've been corrected on X 3 times — ask about it"). Accepts `human_correction` and `delta` after the human responds. Auto-promotes strong patterns (3+) to awareness. |
522
+ | `digest` | **Context cache** — store pre-computed analysis results (codebase audits, subagent explorations) and recall them instead of recomputing. Actions: `store`, `recall`, `read`, `invalidate`. Scoring uses Ebbinghaus decay with Zipf-adjusted half-life. **Benchmarked: 83% token savings on repeated analysis vs. recompute.** |
523
+ | `project_board` | Status board across all AgentRecall projects — same data as `/arstatus`. Returns numbered project list with pending work, blockers, and last activity. Use at the start of any multi-project session. |
524
+ | `project_status` | Deep status for a single project — next actions, blockers, recent journal summary, palace room health. Use after `project_board` to pick and focus. |
525
+ | `bootstrap_scan` | Scan the machine for existing projects (git repos, Claude AutoMemory, CLAUDE.md files). Read-only — no writes. Returns scan results for review before import. |
526
+ | `bootstrap_import` | Import projects discovered by `bootstrap_scan` into AgentRecall. Writes identity, architecture, memory, and trajectory to `~/.agent-recall/`. Safe: never modifies source files. |
390
527
 
391
528
  ### Legacy tools
392
529
 
@@ -404,60 +541,31 @@ The original 22 subsystem tools (palace_write, journal_capture, awareness_update
404
541
  <a href="#5-feedback-loop"><img src="https://img.shields.io/badge/5-FEEDBACK_LOOP-EF4444?style=for-the-badge" alt="Feedback Loop"></a>
405
542
  </p>
406
543
 
407
- > Memory is not a list. It's a compounding system where 1+1+1 > 3. Each subsystem feeds the next — naming enables retrieval, retrieval enables feedback, feedback enables ranking, ranking surfaces the right memory at the right time. After 10 sessions, the system knows more than any individual memory contains.
544
+ > Memory is not a list. It's a compounding system where 1+1+1 > 3. Each subsystem feeds the next — naming enables retrieval, retrieval enables feedback, feedback enables ranking, ranking surfaces the right memory at the right time.
408
545
 
409
546
  ### 1. Auto-Naming
410
547
 
411
- The agent knows content best at the moment of saving. AgentRecall captures that understanding in a semantic slug — not `"mcp-verified"` but `"verified-agentrecall-mcp-22tools-functional"`.
548
+ The agent knows content best at the moment of saving. AgentRecall captures that understanding in a semantic slug — not `"mcp-verified"` but `"verified-agentrecall-mcp-22tools-functional"`. Good naming IS the first layer of retrieval. A well-named memory is 80% findable without any search algorithm.
412
549
 
413
- ```
414
- Content: "Fixed a critical bug where the payment processor crashed on refunds"
415
- → Type detected: bug-fix
416
- → Keywords extracted: payment, processor, crashed, refunds
417
- → Slug generated: bug-fix-payment-processor-crashed
418
- ```
419
-
420
- Good naming IS the first layer of retrieval. A well-named memory is 80% findable without any search algorithm.
550
+ **File naming:** `{date}--{saveType}--{lines}L--{slug}.md` — parseable by agents (`split("--")` → `[date, type, size, topic]`), readable by humans. Line count tells the agent the token cost before opening the file.
421
551
 
422
552
  ### 2. Indexes
423
553
 
424
- Every memory has an address in three index systems:
425
-
426
554
  | Index | What it tracks | Token cost |
427
555
  |-------|---------------|------------|
428
556
  | **Palace index** | Room catalog + salience scores | ~50 tokens to scan |
429
557
  | **Insights index** | Cross-project lessons + keyword matching | ~30 tokens to query |
430
- | **Awareness** | 200-line compounding document (forced merge) | ~200 tokens, but each line carries cross-validated weight |
431
-
432
- Indexes are cheap pointers. The agent scans indexes first, then loads full content only when needed.
558
+ | **Awareness** | 200-line compounding document (forced merge) | ~200 tokens, each line cross-validated |
433
559
 
434
560
  ### 3. Relativity
435
561
 
436
- Memories that relate to each other are connected automatically — no wikilinks needed.
437
-
438
- ```
439
- Agent writes: "JWT refresh rotation prevents session fixation"
440
- → Keywords: jwt, refresh, rotation, session
441
- → Room "architecture" has tags: ["technical"]
442
- → Room "knowledge" has a lesson about "session management"
443
- → Auto-edge created: architecture ←→ knowledge (weight 0.3)
444
- ```
445
-
446
- When you `recall("session security")`, the system surfaces keyword-matched memories across connected rooms. Edges are stored in `graph.json` and are available for traversal — relativity turns isolated memories into a knowledge graph.
562
+ Memories that relate to each other are connected automatically — no wikilinks needed. When you `recall("session security")`, the system surfaces keyword-matched memories across connected rooms. Edges are stored in `graph.json` — relativity turns isolated memories into a knowledge graph.
447
563
 
448
564
  ### 4. Weight + Decay
449
565
 
450
- Not all memories are equal. Salience scoring ensures the right memory surfaces first:
566
+ Not all memories are equal. Salience scoring: `recency(0.30) + access(0.25) + connections(0.20) + urgency(0.15) + importance(0.10)`
451
567
 
452
- ```
453
- salience = recency(0.30) + access(0.25) + connections(0.20) + urgency(0.15) + importance(0.10)
454
- ```
455
-
456
- - Architecture decisions decay at 0.98/day (persistent). Blockers decay at 0.90/day (ephemeral).
457
- - Memories you actually access get stronger. Memories you never revisit fade.
458
- - Demoted insights don't die — they go to the archive. If a future insight matches, they resurrect.
459
-
460
- `recall` applies the **Ebbinghaus forgetting curve** `R(t) = e^(−t/S)` with memory-type-specific strength values — matching the psychological reality of each type:
568
+ `recall` applies the **Ebbinghaus forgetting curve** `R(t) = e^(−t/S)` with memory-type-specific strength values:
461
569
 
462
570
  | Memory type | S (days) | 1-day retention | 1-week retention |
463
571
  |-------------|----------|-----------------|------------------|
@@ -465,24 +573,13 @@ salience = recency(0.30) + access(0.25) + connections(0.20) + urgency(0.15) + im
465
573
  | Knowledge / bug fix (procedural) | 180 | 99% | 96% |
466
574
  | Palace / decisions (semantic) | 9999 | ≈100% | ≈100% |
467
575
 
468
- Old journal noise fades in days. Architecture decisions persist indefinitely. Same query, right results.
576
+ Old journal noise fades in days. Architecture decisions persist indefinitely. **Hot-window boost:** Items from the last 6 hours get a 3× score multiplier, last 24 hours get 2×, last 72 hours get 1.3×.
469
577
 
470
578
  ### 5. Feedback Loop
471
579
 
472
- The system learns what's useful and what's not, using a **Bayesian Beta distribution** — the mathematically optimal estimate of true usefulness from binary observations (`E[Beta(α,β)] = (pos+1)/(pos+neg+2)`):
580
+ The system uses a **Bayesian Beta distribution** — the mathematically optimal estimate of true usefulness from binary observations (`E[Beta(α,β)] = (pos+1)/(pos+neg+2)`). Rating a result "useless" for one query doesn't penalize it for unrelated queries. Feedback is query-aware, not global.
473
581
 
474
- ```
475
- Session 1: recall("auth design") → returns 5 results
476
- Agent rates: result #1 useful, result #3 not useful
477
- → Stored in feedback-log.json with query context
478
-
479
- Session 2: recall("auth patterns") → similar query
480
- → Result #1: Beta(2,1) → E[U]=0.67 → ×1.33 score multiplier
481
- → Result #3: Beta(1,2) → E[U]=0.33 → ×0.67 score multiplier
482
- → Rankings shift: useful memories rise, noise sinks
483
- ```
484
-
485
- No-feedback items stay neutral (multiplier ×1.0). Feedback is query-aware — rating a result "useless" for "auth design" doesn't penalize it for "database schema". The system learns per-context, not globally.
582
+ > **Feedback is now automatic.** The ambient recall hook tracks which memories were surfaced. Human's next message is a correction → negative feedback. Not a correction → positive feedback. No agent action required.
486
583
 
487
584
  ### The Compounding Effect
488
585
 
@@ -495,17 +592,16 @@ Session 50: The agent knows your priorities, blind spots, and communication sty
495
592
  — not because it was told, but because every correction compounded
496
593
  ```
497
594
 
498
- Each layer multiplies the others. Auto-naming makes indexing useful. Indexing makes relativity possible. Relativity makes recall precise. Precise recall generates meaningful feedback. Feedback makes the next recall even better. The loop compounds.
595
+ **Stemming + synonyms:** "deploying" matches "deployment," "ship," and "release." A 19-rule suffix stemmer + 100-pair synonym table — no vector DB needed (keyword mode), zero external dependencies.
499
596
 
500
597
  ---
501
598
 
502
599
  ## SDK API
503
600
 
504
- The `agent-recall-sdk` package exposes the `AgentRecall` class — a programmatic interface to the full memory system. Use it to add persistent, compounding memory to any JS/TS agent framework: LangChain, CrewAI, Vercel AI SDK, AutoGen, or your own.
601
+ The `agent-recall-sdk` package exposes the `AgentRecall` class — a programmatic interface to the full memory system. Use it to add persistent, compounding memory to any JS/TS agent framework.
505
602
 
506
603
  ```typescript
507
604
  import { AgentRecall } from "agent-recall-sdk";
508
-
509
605
  const ar = new AgentRecall({ project: "my-project" });
510
606
  ```
511
607
 
@@ -545,37 +641,14 @@ const ar = new AgentRecall({ project: "my-project" });
545
641
  | `nudge(input)` | `NudgeResult` | Detect contradictions with past decisions |
546
642
  | `synthesize(opts?)` | `ContextSynthesizeResult` | L3 synthesis, optional palace consolidation |
547
643
 
548
- ### LangChain / CrewAI Integration Example
549
-
550
- ```typescript
551
- import { AgentRecall } from "agent-recall-sdk";
552
-
553
- const memory = new AgentRecall({ project: "langchain-app" });
554
-
555
- // Before agent runs — load context
556
- const context = await memory.coldStart();
557
- const insights = await memory.recallInsight("current task description");
558
-
559
- // Inject into system prompt
560
- const systemPrompt = `You have persistent memory:\n${context.summary}\n\nRelevant insights:\n${insights.matches.map(m => m.insight).join("\n")}`;
561
-
562
- // After agent runs — save what was learned
563
- await memory.capture("What did the agent decide?", agentOutput);
564
- await memory.awarenessUpdate([{
565
- insight: "Rate limiting needs token bucket, not fixed window",
566
- evidence: "Fixed window caused burst failures in load test",
567
- applies_when: ["rate-limiting", "api-design", "load-testing"]
568
- }]);
569
- ```
570
-
571
644
  ---
572
645
 
573
646
  ## CLI Commands
574
647
 
575
- The `agent-recall-cli` package provides the `ar` command for terminal workflows, CI pipelines, and quick access to your agent's memory outside of an editor.
648
+ The `agent-recall-cli` package provides the `ar` command for terminal workflows and CI pipelines.
576
649
 
577
650
  ```
578
- ar v3.3.14 — AgentRecall CLI
651
+ ar v3.4.0 — AgentRecall CLI
579
652
 
580
653
  JOURNAL:
581
654
  ar read [--date YYYY-MM-DD] [--section <name>]
@@ -602,11 +675,17 @@ AWARENESS:
602
675
  INSIGHT:
603
676
  ar insight <context> [--limit N]
604
677
 
678
+ SETUP:
679
+ ar setup supabase # interactive Supabase setup wizard
680
+ ar setup supabase --migrate # apply pgvector migration
681
+ ar setup supabase --backfill # re-embed all local memories
682
+
605
683
  META:
606
684
  ar projects
607
685
  ar synthesize [--entries N]
608
686
  ar knowledge write --category <cat> --title "t" --what "w" --cause "c" --fix "f"
609
687
  ar knowledge read [--category <cat>]
688
+ ar bootstrap [--dry-run] [--import] [--project X]
610
689
 
611
690
  HOOKS (auto-wired via settings.json — zero discipline required):
612
691
  ar hook-start # SessionStart: prints identity + insights + watch_for
@@ -652,6 +731,7 @@ L5: Insight Index recall_insight "cross-project experience"
652
731
  awareness-state.json # Structured awareness data
653
732
  awareness-archive.json # Demoted insights (preserved, not deleted)
654
733
  insights-index.json # Cross-project insight matching
734
+ config.json # Optional: Supabase URL + keys (never git-committed)
655
735
  projects/
656
736
  <project>/
657
737
  journal/
@@ -668,6 +748,7 @@ L5: Insight Index recall_insight "cross-project experience"
668
748
  rooms/
669
749
  goals/ # Active goals, evolution
670
750
  architecture/ # Technical decisions, patterns
751
+ decisions/ # Decision trails with prior/posterior tracking
671
752
  blockers/ # Current and resolved
672
753
  alignment/ # Human corrections
673
754
  knowledge/ # Learned lessons by category
@@ -695,55 +776,31 @@ L5: Insight Index recall_insight "cross-project experience"
695
776
 
696
777
  ---
697
778
 
698
- ## Real Results
779
+ ## Benchmarked Token Savings
699
780
 
700
- Validated over 42+ sessions across 5 production projects:
701
- - Cold-start: **5 min → 2 seconds** (palace-first loading, ~400 tokens)
702
- - Decision retention: **0% → 100%** across sessions
703
- - Misunderstanding caught before wrong work: **6+ instances** via `check` before publish/deploy
704
- - Repeated mistakes prevented: **3 instances** via cross-project insight recall
781
+ We ran two controlled benchmarks: a 5-round A/B test (Next.js + Drizzle + Stripe project) and a 10-round v3.3.16 benchmark validating `digest` cache, `arsaveall`, and cross-project recall. **Read this table honestly:** for simple throwaway tasks, AR is pure overhead. For anything with 3+ sessions, corrections, or multiple agents, it pays for itself — and the savings compound.
705
782
 
706
- ### Measured Token Cost (v3.3.14, 5 rounds)
783
+ | Scenario | Without AR | With AR | **Saved** |
784
+ |----------|:---------:|:------:|:--------:|
785
+ | **A: Simple** (2 sessions, 0 corrections) | 567 | 1,131 | **+99% overhead** |
786
+ | **B: Medium** (5 sessions, 1 correction) | 6,220 | 4,382 | **-30%** |
787
+ | **C: Complex** (20 sessions, 5 corrections) | 40,910 | 17,520 | **-57%** |
788
+ | **D: Multi-agent** (3 agents × 5 sessions) | 20,781 | 13,140 | **-37%** |
789
+ | **E: Digest cache** (repeated analysis, 1 recall hit) | ~2,400 | ~400 | **-83%** |
707
790
 
708
- | Surface | What it returns | Measured tokens |
709
- |---------|----------------|-----------------|
710
- | `hook-start` (stdout) | identity + watch_for + 3 insights + recent + cross-project hint | ~215 |
711
- | `session_start` (MCP) | full session context — all fields | ~601 |
712
- | `check` (MCP) | watch_for patterns + past deltas | ~80 |
713
- | **Total session overhead** | | **~896 tokens** |
791
+ **Break-even: ~3-4 sessions.** After that, every session with AR is cheaper than without.
714
792
 
715
- Each prevented correction ≈ **1,500 tokens saved** (re-explanation + wrong work + retry).
716
- Breakeven: **less than 1 correction prevented per session** covers the overhead.
717
- At 42 sessions with avg 1.5 corrections prevented: **~94,000 tokens saved** vs ~37,600 overhead.
793
+ ### Where the Savings Come From
718
794
 
719
- ### What the 5 Test Rounds Verified
795
+ | Source | Without AR cost | With AR cost | Why |
796
+ |--------|:-:|:-:|-----|
797
+ | **Context rebuild** | Up to ~1,100+ tokens/session | Fixed ~385 tokens (cold start) | AR loads palace context in one call |
798
+ | **Correction retention** | ~800 tokens per repeat | 0 (stored once, never repeated) | Biggest single savings driver in long projects |
799
+ | **Clarification avoidance** | ~400 tokens/session | 0 (already loaded) | Steady per-session savings |
800
+ | **Cross-project recall** | ~500 tokens per insight | ~350 tokens (automatic recall) | Compounds across projects |
801
+ | **Digest cache** | ~2,400 tokens (full re-analysis) | ~400 tokens (recall stored digest) | 83% savings on repeated heavy analysis |
720
802
 
721
- **Round 1 — hook-start:**
722
- Fires on session open (with per-session lock to avoid double-fire). Output: project identity, past correction warnings (watch_for), top 3 awareness insights, today's journal brief, cross-project hint. All in 9 lines.
723
-
724
- **Round 2 — capture / palace write / search / walk:**
725
- - `capture "bug fix"` → routes to journal log with auto-tags
726
- - `palace write architecture "..."` → writes to room with fan-out
727
- - `search "journal crash fix"` → keyword match finds the entry from 2 minutes ago
728
- - `palace walk --depth active` → loads 5 rooms, top 10 insights, architecture decisions in one JSON
729
-
730
- **Round 3 — hook-correction / hook-end / MCP tools:**
731
- - `hook-correction` with no-correction prompt → silent exit (correct)
732
- - `hook-correction` with correction ("no use patch not minor") → silent capture, exit 0
733
- - `hook-end` → exit 0, auto-log entry
734
- - MCP `session_start` → 601 tokens, all 7 fields populated
735
- - MCP `check(goal="publish v3.3.14", confidence="high")` → 80 tokens, 1 watch_for pattern surfaced
736
-
737
- **Round 4 — cross-source recall competition (v3.3.14):**
738
- - `recall("edge functions cold start")` → palace + journal + insight all queried; RRF merged by rank position — no source dominated by raw score inflation
739
- - Old journal entries (>3 days) correctly faded via Ebbinghaus S=2; palace decisions surfaced regardless of age
740
-
741
- **Round 5 — feedback loop (v3.3.14):**
742
- - `recall("auth design")` + feedback `{useful: true}` → Beta(2,1) → ×1.33 on next query
743
- - `recall("auth design")` + feedback `{useful: false}` → Beta(1,2) → ×0.67 penalty
744
- - Zero-feedback items unchanged (Beta(1,1) → ×1.0 neutral)
745
-
746
- 172 tests (129 core + 4 smoke + 28 SDK + 11 CLI), 0 failures. Build clean.
803
+ All benchmark code: [`benchmark/run.mjs`](benchmark/run.mjs), [`benchmark/ab-comparison.mjs`](benchmark/ab-comparison.mjs), and [`benchmark/v3316-benchmark.mjs`](benchmark/v3316-benchmark.mjs). Run them yourself: `node benchmark/run.mjs && node benchmark/ab-comparison.mjs`.
747
804
 
748
805
  ---
749
806
 
@@ -751,11 +808,14 @@ Fires on session open (with per-session lock to avoid double-fire). Output: proj
751
808
 
752
809
  | Document | Description |
753
810
  |----------|-------------|
811
+ | **[→ Command Reference](docs/commands.md)** | **Full guide to `/arstatus`, `/arstart`, `/arsave`, `/arsaveall` — example outputs, modes, palace rules, troubleshooting** |
754
812
  | [Intelligent Distance Protocol](docs/intelligent-distance-protocol.md) | The foundational theory — why the gap between human and AI is structural, and how to navigate it |
755
813
  | [Scoring Design Rationale](docs/SCORING.md) | Why the scoring system works this way — RRF, Ebbinghaus, Beta distribution, and the bugs they fix |
756
814
  | [MCP Adapter Spec](docs/mcp-adapter-spec.md) | Technical spec for building adapters on top of AgentRecall |
757
815
  | [SDK Design](docs/sdk-design.md) | Design doc for the SDK architecture |
758
- | [Upgrade v3.4](UPGRADE-v3.4.md) | Changelog: weekly roll-up, palace-first cold start, promotion verification |
816
+ | [Upgrade v3.4](UPGRADE-v3.4.md) | Changelog: semantic recall, pgvector backend, 10 MCP tools, bootstrap, palace decisions room |
817
+ | [MCP Server README](packages/mcp-server/README.md) | Focused guide for Claude Code / Cursor / Windsurf users |
818
+ | [Core SDK README](packages/core/README.md) | SDK API reference for building with AgentRecall programmatically |
759
819
 
760
820
  ---
761
821
 
@@ -786,193 +846,60 @@ MIT License.
786
846
  ---
787
847
 
788
848
  <p align="center">
789
- <a href="#arsave-and-arstart"><img src="https://img.shields.io/badge/%2Farsave-保存会话-FF6B6B?style=for-the-badge" alt="/arsave"></a>
790
- <a href="#arsave-and-arstart"><img src="https://img.shields.io/badge/%2Farstart-加载上下文-4ECDC4?style=for-the-badge" alt="/arstart"></a>
849
+ <a href="#arstatus-arsave-arstart-和-arsaveall"><img src="https://img.shields.io/badge/%2Farstatus-从这里开始-22C55E?style=for-the-badge" alt="/arstatus"></a>
850
+ <a href="#arstatus-arsave-arstart-和-arsaveall"><img src="https://img.shields.io/badge/%2Farstart-加载上下文-4ECDC4?style=for-the-badge" alt="/arstart"></a>
851
+ <a href="#arstatus-arsave-arstart-和-arsaveall"><img src="https://img.shields.io/badge/%2Farsave-保存会话-FF6B6B?style=for-the-badge" alt="/arsave"></a>
852
+ <a href="#arstatus-arsave-arstart-和-arsaveall"><img src="https://img.shields.io/badge/%2Farsaveall-批量保存-FFD93D?style=for-the-badge" alt="/arsaveall"></a>
791
853
  </p>
792
854
  <p align="center">
793
855
  <img src="https://img.shields.io/badge/自动-hook--start-8B5CF6?style=for-the-badge" alt="hook-start">
794
856
  <img src="https://img.shields.io/badge/自动-hook--correction-F97316?style=for-the-badge" alt="hook-correction">
795
857
  <img src="https://img.shields.io/badge/自动-hook--end-06B6D4?style=for-the-badge" alt="hook-end">
796
858
  </p>
797
- <p align="center">
798
- <a href="#记忆如何复合增长"><img src="https://img.shields.io/badge/1-自动命名-5D34F2?style=for-the-badge" alt="自动命名"></a>
799
- <a href="#记忆如何复合增长"><img src="https://img.shields.io/badge/2-索引-0EA5E9?style=for-the-badge" alt="索引"></a>
800
- <a href="#记忆如何复合增长"><img src="https://img.shields.io/badge/3-关联性-10B981?style=for-the-badge" alt="关联性"></a>
801
- <a href="#记忆如何复合增长"><img src="https://img.shields.io/badge/4-权重与衰减-F59E0B?style=for-the-badge" alt="权重与衰减"></a>
802
- <a href="#记忆如何复合增长"><img src="https://img.shields.io/badge/5-反馈回路-EF4444?style=for-the-badge" alt="反馈回路"></a>
803
- </p>
804
859
 
805
- ## `/arsave` 和 `/arstart`
860
+ ## `/arstatus`、`/arsave`、`/arstart` 和 `/arsaveall`
806
861
 
807
- > **两个命令,ezpz。**
862
+ > [!IMPORTANT]
863
+ > **每次新会话都先运行 `/arstatus`。** 它会显示你所有项目的状态、待完成的工作、阻塞项,让你用数字选择下一步——无需记住项目名称。没有它,全新的 agent 根本不知道从哪里开始。
808
864
 
809
865
  | 命令 | 时机 | 功能 |
810
866
  |------|------|------|
811
- | **`/arsave`** | 会话结束时 | 写入日志 + 整合到记忆宫殿 + 更新感知 + 可选 git 推送 |
812
- | **`/arstart`** | 会话开始时 | 召回跨项目洞察 + 遍历宫殿 + 加载上下文 |
867
+ | ⭐ **`/arstatus`** | **每次会话——先运行这个** | **跨所有项目的状态看板:待办事项、阻塞项、编号选择列表。真正的冷启动。** |
868
+ | **`/arstart`** | 选好项目后 | 加载单个项目的深度上下文:宫殿房间、纠正记录、任务相关召回 |
869
+ | **`/arsave`** | 会话结束时 | 写入日志 + 整合到记忆宫殿 + 更新感知 |
870
+ | **`/arsaveall`** | 一天结束时(多会话) | **一次性批量保存所有并行会话** — 扫描、合并、去重、完成 |
813
871
 
814
- 会话结束时输入 `/arsave`,所有内容自动保存。下次开始时输入 `/arstart`,所有上下文自动恢复。
872
+ **会话流程:** `/arstatus` → 输入编号 → `/arstart <项目>` → 工作 → `/arsave`。
815
873
 
816
- ```bash
817
- # 安装命令(一次性,仅 Claude Code)
818
- mkdir -p ~/.claude/commands
819
- curl -o ~/.claude/commands/arsave.md https://raw.githubusercontent.com/Goldentrii/AgentRecall/main/commands/arsave.md
820
- curl -o ~/.claude/commands/arstart.md https://raw.githubusercontent.com/Goldentrii/AgentRecall/main/commands/arstart.md
821
- ```
874
+ ### 你会看到什么
822
875
 
823
- ### 效果对比
876
+ 输入 `/arstatus` → 一眼看清所有项目进展:
824
877
 
825
878
  ```
826
- 没有 AgentRecall 有 AgentRecall
827
- ────────────── ────────────
828
-
829
- 第 1 天:构建单仓 第 1 天:/arstart → /arsave
830
- 第 2 天:"什么单仓?" 第 2 天:/arstart
831
- → 20 分钟重新解释 → 2 秒:加载所有决策
832
- → 智能体重复同样的错误 → 知道"不要版本膨胀"
833
- → 忘记你的优先级 → 知道"arsave 要放首位"
834
- → 遗漏一半的任务 → 自动推送两个仓库
835
- ```
879
+ ──────────────────────────────────────────────────────────────
880
+ AgentRecall 状态看板 2026-04-21 5 个项目
881
+ ──────────────────────────────────────────────────────────────
836
882
 
837
- ### 三层价值
883
+ 1 ⚠ novada-site 2026-04-21 阻塞
884
+ 阻塞:缺少 .env.local — Phase 1 无法继续
838
885
 
839
- **第一层(5 秒):** 让你的 AI agent 记住上次会话发生了什么。
886
+ 2 ● novada-mcp 2026-04-21
887
+ 下一步:修复 novada_search POST /request → 发布 v0.8.0
840
888
 
841
- **第二层(30 秒):** 每次你纠正 agent——"不,不是那个版本"、"先问我"——这个纠正被永久存储,并在 agent 再犯同样错误之前被召回。10 次会话后,你的 agent 理解你的优先级、你的沟通风格、你的不可妥协项。
889
+ 3 ● prismma-scraper 2026-04-17
890
+ 下一步:UI 升级 Option A — 浅色模式 + 3D 视觉
842
891
 
843
- **第三层(2 分钟):** [智能距离协议](https://github.com/Goldentrii/AgentRecall/wiki/Intelligent-Distance)。人类思维和 AI 行动之间的结构性鸿沟无法消除——但可以在每次会话中更好地穿越。纠正就是训练数据。200 行感知上限强制质量优于数量。跨项目洞察意味着学到一次的经验到处适用。
844
-
845
- ### 真实会话流程
846
-
847
- 以下来自一个真实的多日项目,人类给出了分散、非线性的指令。智能体全程使用 AgentRecall:
892
+ 4 ✓ AgentRecall 2026-04-21 已完成
893
+ 收集真实生产数据中
848
894
 
895
+ ──────────────────────────────────────────────────────────────
896
+ 输入编号,或:
897
+ N 新项目(带记忆——agent 了解你的完整历史)
898
+ X 新项目(空白状态——无历史上下文,纯客观模式)
899
+ ──────────────────────────────────────────────────────────────
849
900
  ```
850
- 会话 1(周二) 会话 2(周三,不同的智能体)
851
- ────────── ────────────────────────
852
-
853
- /arstart /arstart
854
- │ │
855
- ├─ session_start() ──→ 身份 + 洞察 ├─ session_start() ──→ 加载周二
856
- │ 活跃房间 + 跨项目匹配 │ 架构决策(约 400 token),
857
- │ watch_for 警告 │ watch_for: "结构化输入"
858
- │ │
859
- ├─ recall("SDK CLI 版本") ──→ ├─ recall("SDK CLI 单仓") ──→
860
- │ • "结构化分散的输入" │ • "不要版本膨胀"
861
- │ • "先搜索再构建" │ • "arsave 放在最显眼的位置"
862
- │ • "模糊时询问,明确时执行" │
863
- │ ├─ 从会话 1 离开的地方
864
- ▼ │ 无缝继续
865
- 人类:"我们需要 SDK、CLI, │
866
- 更新 README,修复版本号" ▼
867
- │ 人类:"发布到 npm,
868
- ├─ check(goal="SDK+CLI+README", 更新两个 GitHub 仓库"
869
- │ confidence="medium") │
870
- │ 检测到 4 个任务项 ├─ 无需重新解释。
871
- │ → 呈现方案 → 人类确认 │ 智能体已经知道单仓结构、
872
- │ │ 包名和版本策略。
873
- ├─ 按顺序执行: │
874
- │ 1. 核心提取 ✓ └─ 2 分钟完成
875
- │ 2. 工具逻辑拆分 ✓ (没有 AgentRecall
876
- │ 3. MCP 封装 ✓ 需要 2-8 分钟冷启动)
877
- │ 4. SDK + CLI ✓
878
- │
879
- /arsave
880
- │
881
- └─ session_end(summary, insights, trajectory)
882
- → 日志 + 感知 + 宫殿 — 一次调用全部完成
883
- ```
884
-
885
- ---
886
-
887
- ## 为什么选择 AgentRecall
888
-
889
- **AgentRecall 不是记忆工具,而是学习循环。**
890
-
891
- 你的智能体在会话之间不是真的遗忘——它们是记不清楚、分不清主次,甚至听不懂你在说什么。AgentRecall 像人类记忆一样运作:把不重要的东西冬眠起来,但随时可以唤醒。更重要的是,它让智能体越用越懂你。
892
-
893
- 记忆是机制,理解才是目标。每次你纠正智能体 —— "不要那个版本"、"把这个部分放在最前面"、"做之前先问我" —— 这个纠正会被存储、加权、并在下次自动召回。10 个会话后,你的智能体不只是记住了你的项目,它理解了你的思维方式:你的优先级、你的沟通风格、你的底线。
894
-
895
- 这就是**智能距离协议** —— 不是消除人类与 AI 之间的差距(这个差距是结构性的),而是每次会话都导航得更好。
896
-
897
- - **你的智能体学会理解你的思维。** 人类本身就是不一致的 —— 我们会从 A 直接跳到 E,跳过 B、C、D。我们会忘记昨天说的话,会在句子中间改变优先级。AgentRecall 捕获每一次纠正,在下一个错误发生之前浮现。你的意图和智能体行为之间的差距,每次会话都在缩小。
898
-
899
- - **复合感知,而非无限日志。** 记忆上限 200 行。新洞察要么与已有的合并(增强),要么替换最弱的。100 个会话后,感知文件仍然是 200 行 —— 但每一行都承载着经过交叉验证的确认观察。
900
-
901
- - **跨项目召回。** 在一个项目中学到的教训适用于所有项目。上个月做了限流器?今天在另一个项目构建时,那个教训会自动浮现。
902
-
903
- - **近乎通用的兼容性。** MCP 服务器支持所有 MCP 兼容智能体(Claude Code、Cursor、Windsurf、VS Code、Codex)。SDK 支持任何 JS/TS 框架(LangChain、CrewAI、Vercel AI SDK、自定义智能体)。CLI 支持终端和 CI 工作流。一套记忆系统,覆盖所有场景。
904
-
905
- - **零云端,零遥测,全部本地。** 一切都是磁盘上的 markdown。在 Obsidian 中浏览,在终端中 grep,在 git 中版本管理。无需账户、API 密钥或锁定。
906
-
907
- ### 用例一:跳跃式思维的人类
908
-
909
- 一个真实会话,人类在两天项目中给出了非线性、分散的指令:
910
-
911
- > 人类:"我们需要 SDK、CLI,还有更新 README,哦对了 npm 版本号也错了,一起修"
912
-
913
- 没有 AgentRecall,智能体猜测优先级,遗漏项目。有 AgentRecall:
914
-
915
- | 智能体已经知道的 | 怎么知道的 |
916
- |---|---|
917
- | "这个人沟通是分散的 —— 先结构化成模块再执行" | 3 个先前会话的 `awareness_update` |
918
- | "模糊时询问,明确时执行" | 上周 `alignment_check` 存储的纠正 |
919
- | "不要版本膨胀 —— 这个人很在意语义化版本" | 会话中 `nudge` 捕获,立即召回 |
920
-
921
- 结果:智能体呈现结构化的 4 步方案,人类确认,零返工。没有 AgentRecall 的新智能体会猜错版本号、把最重要的功能埋在 README 深处、并且不测试就发布。
922
-
923
- ### 用例二:跨项目经验传递
924
901
 
925
- 一个工程师构建了带限流的代理服务器(项目 A)。三周后,开始构建 API 网关(项目 B)。
926
-
927
- ```
928
- 在项目 B 运行 /arstart:
929
- recall_insight:"限流防止成本失控"
930
- → 来源:项目 A,确认 3 次,严重性:critical
931
- → 适用场景:["api", "proxy", "rate-limit", "cost"]
932
- → 项目 A 的教训在项目 B 中自动浮现
933
- ```
934
-
935
- 工程师从未提到限流。AgentRecall 自动匹配项目上下文与全局洞察索引。
936
-
937
- ### 用例三:纠正只发生一次
938
-
939
- 会话 1:智能体把补丁版本设为 4.0.0。人类纠正:"这是版本膨胀,用 3.3.4。"
940
-
941
- 会话 2(第二天,不同的智能体):感知系统已包含"不要版本膨胀 —— 这个人在意保守的版本策略"。新智能体第一次就做对了。
942
-
943
- 没有 AgentRecall,同样的纠正需要一次又一次。有 AgentRecall,**每个纠正只发生一次。**
944
-
945
- ---
946
-
947
- ## 三种使用方式
948
-
949
- **MCP** — 面向 AI 智能体(Claude Code、Cursor、Windsurf、VS Code、Codex):
950
- ```bash
951
- claude mcp add --scope user agent-recall -- npx -y agent-recall-mcp
952
- ```
953
-
954
- **SDK** — 面向任何 JS/TS 应用(LangChain、CrewAI、Vercel AI SDK、自定义):
955
- ```typescript
956
- import { AgentRecall } from "agent-recall-sdk";
957
- const memory = new AgentRecall({ project: "my-app" });
958
- await memory.capture("用什么技术栈?", "Next.js + Postgres");
959
- ```
960
-
961
- **CLI** — 面向终端工作流和 CI:
962
- ```bash
963
- npx agent-recall-cli capture "用什么技术栈?" "Next.js + Postgres"
964
- npx agent-recall-cli palace walk --depth active
965
- ```
966
-
967
- ---
968
-
969
- ## AgentRecall 是什么?
970
-
971
- 一个**学习系统**,弥合人类思维方式与 AI 智能体工作方式之间的差距。不是日志,不是数据库——是一个复合循环,每一次纠正、决策和洞察都让下一次会话比上一次更好。
972
-
973
- **问题:** AI 智能体不是真的遗忘——它们主要是无法抓住人类以为的重点。记不清楚优先级,分不清主次,教训进入休眠状态,同样的误解重复发生因为没人存储那次纠正行为。你的意图、目标和智能体行为之间的差距和割裂导致最终项目效果不佳。
974
-
975
- **解决方案:** AgentRecall 将知识存储在五层记忆金字塔中——从快速捕获到跨项目洞察——并通过强制压缩让记忆随时间增值。但更重要的是,它缩小了**智能距离**差距:每一次人类的纠正都被捕获、加权、并在智能体犯同样错误之前被召回。
902
+ ### 效果对比
976
903
 
977
904
  | 没有 AgentRecall | 有 AgentRecall |
978
905
  |-----------------|---------------|
@@ -982,12 +909,19 @@ npx agent-recall-cli palace walk --depth active
982
909
  | 平面记忆文件无限增长 | 200 行感知上限,强制合并或替换 |
983
910
  | 知识锁在单个项目 | 跨项目洞察按关键词匹配 |
984
911
 
912
+ ```bash
913
+ # 安装命令(一次性,仅 Claude Code)
914
+ mkdir -p ~/.claude/commands
915
+ curl -o ~/.claude/commands/arstatus.md https://raw.githubusercontent.com/Goldentrii/AgentRecall/main/commands/arstatus.md
916
+ curl -o ~/.claude/commands/arstart.md https://raw.githubusercontent.com/Goldentrii/AgentRecall/main/commands/arstart.md
917
+ curl -o ~/.claude/commands/arsave.md https://raw.githubusercontent.com/Goldentrii/AgentRecall/main/commands/arsave.md
918
+ curl -o ~/.claude/commands/arsaveall.md https://raw.githubusercontent.com/Goldentrii/AgentRecall/main/commands/arsaveall.md
919
+ ```
920
+
985
921
  ---
986
922
 
987
923
  ## 快速开始
988
924
 
989
- ### MCP 服务器(面向 AI 智能体)
990
-
991
925
  ```bash
992
926
  # Claude Code
993
927
  claude mcp add --scope user agent-recall -- npx -y agent-recall-mcp
@@ -998,7 +932,7 @@ claude mcp add --scope user agent-recall -- npx -y agent-recall-mcp
998
932
  # VS Code — .vscode/mcp.json
999
933
  { "servers": { "agent-recall": { "command": "npx", "args": ["-y", "agent-recall-mcp"] } } }
1000
934
 
1001
- # Codex — ~/.codex/config.toml
935
+ # Codex
1002
936
  codex mcp add agent-recall -- npx -y agent-recall-mcp
1003
937
  ```
1004
938
 
@@ -1009,181 +943,80 @@ curl -o ~/.claude/skills/agent-recall/SKILL.md \
1009
943
  https://raw.githubusercontent.com/Goldentrii/AgentRecall/main/SKILL.md
1010
944
  ```
1011
945
 
1012
- ### SDK(面向 JS/TS 应用)
946
+ ---
1013
947
 
1014
- ```bash
1015
- npm install agent-recall-sdk
1016
- ```
948
+ ## 语义召回 — pgvector (v3.4.0)
1017
949
 
1018
- ```typescript
1019
- import { AgentRecall } from "agent-recall-sdk";
950
+ > [!NOTE]
951
+ > **v3.4.0 新功能。** 默认关键词召回无需任何配置。当关键词搜索遇到天花板时——同义词、改写查询、多语言——升级到 Supabase pgvector 后端。
1020
952
 
1021
- const memory = new AgentRecall({ project: "my-app" });
1022
- await memory.capture("用什么 ORM?", "Drizzle — 类型安全、轻量");
1023
- await memory.palaceWrite("architecture", "技术栈:Next.js 16 + Drizzle + Postgres");
1024
- const context = await memory.coldStart();
1025
- ```
1026
-
1027
- ### CLI(面向终端和 CI)
953
+ 关键词搜索匹配词汇,语义搜索匹配**含义**。升级后:`recall("会话过期")` 也能找到"token 刷新"和"认证超时"相关的条目,无需手动添加同义词。
1028
954
 
1029
955
  ```bash
1030
- npm install -g agent-recall-cli
1031
-
1032
- ar capture "用什么 ORM?" "Drizzle" --project my-app
1033
- ar palace walk --depth active
1034
- ar insight "构建认证中间件"
1035
- ```
1036
-
1037
- ---
956
+ # 第 1 步 — 交互式配置向导
957
+ ar setup supabase
1038
958
 
1039
- ## 智能体使用流程
959
+ # 第 2 步 — 将 pgvector 迁移应用到你的 Supabase 项目
960
+ ar setup supabase --migrate
1040
961
 
1041
- ### 会话开始 (`/arstart`)
1042
- ```
1043
- session_start() → 身份、洞察、活跃房间、跨项目匹配、最近活动、watch_for 预警 — 一次调用
962
+ # 第 3 步 — 完成。运行 /arstart — 下次会话自动回填。
1044
963
  ```
1045
964
 
1046
- ### 工作中
1047
- ```
1048
- remember("我们决定用 GraphQL 替代 REST") → 自动分类并路由到正确的存储
1049
- recall("认证设计") → 搜索所有存储,排名结果
1050
- check(goal="构建认证", confidence="medium") → 验证理解,获取预警
1051
- ```
965
+ 本地文件仍为数据源。Supabase 是派生的读取索引 — 随时可删除并用 `ar setup supabase --backfill` 重建。
1052
966
 
1053
- ### 会话结束 (`/arsave`)
1054
- ```
1055
- session_end(summary="...", insights=[...], trajectory="...") → 日志 + 感知 + 整合
1056
- ```
967
+ **所需环境变量:** `SUPABASE_URL` + `SUPABASE_SERVICE_ROLE_KEY` + `OPENAI_API_KEY`(或 `VOYAGE_API_KEY`)。全部可选 — 不配置时 AgentRecall 完全正常运行。
968
+
969
+ **优雅降级:** Supabase 不可达时,`recall()` 静默回退到本地关键词搜索,零行为变化。
1057
970
 
1058
971
  ---
1059
972
 
1060
- ## 5 个 MCP 工具
973
+ ## 10 个 MCP 工具
1061
974
 
1062
- AgentRecall 目前只向 agent 提供 5 个工具。每个工具内部组合多个子系统 — agent 不需要了解内部管道。
975
+ AgentRecall 目前向 agent 提供 10 个工具。每个工具内部组合多个子系统——agent 不需要了解内部管道。
1063
976
 
1064
977
  | 工具 | 功能 |
1065
978
  |------|------|
1066
- | `session_start` | 加载项目上下文。返回身份、洞察、活跃房间、跨项目匹配、最近活动、以及来自历史纠正的 `watch_for` 预警。一次调用,约 400 token。 |
1067
- | `remember` | 保存记忆。自动分类内容(bug 修复、架构决策、洞察、会话笔记)并路由到正确的存储。自动生成语义化名称便于未来检索。 |
1068
- | `recall` | 通过**互惠排名融合(RRF)**一次搜索所有记忆 — 每个来源内部独立排名,再按位置合并,避免任何单一来源靠原始分数主导结果。返回带稳定 ID 的排名结果。支持 `feedback` 评价:正面提升排名,负面降低。查询感知 — 某次搜索的反馈不影响无关查询。 |
1069
- | `session_end` | 一次调用保存全部。写入日志、更新感知、整合到宫殿、归档被替换的洞察(不删除 — 支持复活)。 |
1070
- | `check` | 记录你对人类意图的理解。返回历史纠正模式的 `watch_for` 预警。支持记录 `human_correction` 和 `delta`。3+ 次的强模式自动提升为感知洞察。 |
1071
-
1072
- ### 旧版工具
1073
-
1074
- 原始 22 个子系统工具(palace_write、journal_capture、awareness_update 等)通过 SDK 和 CLI 仍然可用,适用于向后兼容和高级用例。MCP 服务器默认不注册这些工具。
979
+ | `session_start` | 加载项目上下文。返回身份、洞察、活跃房间、跨项目匹配、watch_for 预警。约 400 token。 |
980
+ | `remember` | 保存记忆。自动分类并路由到正确的存储(日志、宫殿、知识库或感知系统)。 |
981
+ | `recall` | 通过 **RRF** 一次搜索所有记忆。支持 `feedback` 评价:正面提升排名,负面降低。查询感知。 |
982
+ | `session_end` | 一次调用保存全部:写日志、更新感知、整合宫殿、归档被替换洞察。 |
983
+ | `check` | 记录对人类意图的理解。返回 `watch_for` 预警。3+ 次强模式自动提升为感知洞察。 |
984
+ | `digest` | **上下文缓存**。存储耗时分析结果(代码库探索、API 审计)。实测节省 83% token。 |
985
+ | `project_board` | 跨所有项目的状态看板,等同于 `/arstatus`。返回编号项目列表、待办、阻塞项。 |
986
+ | `project_status` | 单个项目的深度状态:下一步行动、阻塞项、最近日志摘要、宫殿健康度。 |
987
+ | `bootstrap_scan` | 扫描机器上的现有项目(git 仓库、Claude AutoMemory、CLAUDE.md)。只读,不写入。 |
988
+ | `bootstrap_import` | 将 `bootstrap_scan` 发现的项目导入 AgentRecall。安全:不修改源文件。 |
1075
989
 
1076
990
  ---
1077
991
 
1078
992
  ## 记忆如何复合增长
1079
993
 
1080
- <p align="center">
1081
- <a href="#1-自动命名"><img src="https://img.shields.io/badge/1-自动命名-5D34F2?style=for-the-badge" alt="自动命名"></a>
1082
- <a href="#2-索引"><img src="https://img.shields.io/badge/2-索引-0EA5E9?style=for-the-badge" alt="索引"></a>
1083
- <a href="#3-关联性"><img src="https://img.shields.io/badge/3-关联性-10B981?style=for-the-badge" alt="关联性"></a>
1084
- <a href="#4-权重与衰减"><img src="https://img.shields.io/badge/4-权重与衰减-F59E0B?style=for-the-badge" alt="权重与衰减"></a>
1085
- <a href="#5-反馈回路"><img src="https://img.shields.io/badge/5-反馈回路-EF4444?style=for-the-badge" alt="反馈回路"></a>
1086
- </p>
1087
-
1088
- > 记忆不是清单,而是一个 1+1+1 > 3 的复合系统。每个子系统喂养下一个 — 命名使检索成为可能,检索使反馈成为可能,反馈使排名成为可能,排名让正确的记忆在正确的时间浮现。10 个会话后,系统知道的比任何单条记忆都多。
1089
-
1090
- ### 1. 自动命名
1091
-
1092
- Agent 在保存的瞬间对内容理解最深。AgentRecall 把这种理解捕获为语义化的名称 — 不是 `"mcp-verified"` 而是 `"verified-agentrecall-mcp-22tools-functional"`。
1093
-
1094
- ```
1095
- 内容: "修复了支付处理器在退款时崩溃的严重 bug"
1096
- → 类型检测: bug-fix
1097
- → 关键词提取: payment, processor, crashed, refunds
1098
- → 生成名称: bug-fix-payment-processor-crashed
1099
- ```
1100
-
1101
- 好的命名本身就是检索的第一层。一个命名良好的记忆,不需要搜索算法就能被找到 80%。
1102
-
1103
- ### 2. 索引
994
+ 不是所有记忆都平等。五个子系统相互喂养,自动命名让索引有意义,索引让关联性成为可能,关联性让检索精准,精准检索产生有意义的反馈,反馈让下一次检索更好。
1104
995
 
1105
- 每条记忆在三个索引系统中都有地址:
996
+ **显著性评分:** `时效性(0.30) + 访问频率(0.25) + 连接数(0.20) + 紧迫性(0.15) + 重要性(0.10)`
1106
997
 
1107
- | 索引 | 追踪什么 | Token 开销 |
1108
- |------|---------|-----------|
1109
- | **宫殿索引** | 房间目录 + 显著性评分 | 扫描约 50 token |
1110
- | **洞察索引** | 跨项目教训 + 关键词匹配 | 查询约 30 token |
1111
- | **感知文档** | 200 行复合文档(强制合并) | 约 200 token,但每一行都承载交叉验证的权重 |
998
+ **Ebbinghaus 衰减 `R(t) = e^(−t/S)`:**
1112
999
 
1113
- 索引是轻量指针。Agent 先扫描索引,只在需要时才加载完整内容。
1000
+ | 记忆类型 | S(天) | 1天后 | 1周后 |
1001
+ |----------|---------|-------|-------|
1002
+ | 日志(情景) | 2 | 60% | ~7% |
1003
+ | 知识/Bug修复(程序) | 180 | 99% | 96% |
1004
+ | 宫殿/架构决策(语义) | 9999 | ≈100% | ≈100% |
1114
1005
 
1115
- ### 3. 关联性
1116
-
1117
- 相关的记忆会自动连接 — 无需手写 wikilinks。
1118
-
1119
- ```
1120
- Agent 写入: "JWT 刷新令牌轮换防止会话固定攻击"
1121
- → 关键词: jwt, refresh, rotation, session
1122
- → "architecture" 房间标签: ["technical"]
1123
- → "knowledge" 房间有 "session management" 教训
1124
- → 自动创建边: architecture ←→ knowledge (权重 0.3)
1125
- ```
1126
-
1127
- 当你 `recall("会话安全")` 时,系统不只是关键词匹配 — 它沿着边跳 1 步,从关联房间中浮现相关记忆。关联性把孤立的记忆变成知识图谱。
1128
-
1129
- ### 4. 权重与衰减
1130
-
1131
- 不是所有记忆都平等。显著性评分确保最重要的记忆先浮现:
1132
-
1133
- ```
1134
- 显著性 = 时效性(0.30) + 访问频率(0.25) + 连接数(0.20) + 紧迫性(0.15) + 重要性(0.10)
1135
- ```
1136
-
1137
- - 架构决策以 0.98/天 衰减(持久)。阻塞项以 0.90/天 衰减(短暂)。
1138
- - 你实际访问的记忆越来越强。从不回顾的记忆逐渐淡化。
1139
- - 被替换的洞察不会消亡 — 它们进入归档。如果未来的洞察匹配,它们会复活。
1140
-
1141
- `recall` 基于**艾宾浩斯遗忘曲线**(1885)`R(t) = e^(−t/S)` 对不同记忆类型设定不同衰减强度:
1142
-
1143
- | 记忆类型 | S(天) | 1天后保留率 | 1周后保留率 |
1144
- |----------|---------|------------|------------|
1145
- | 日志(情景记忆) | 2 | 60% | ~7% |
1146
- | 知识 / Bug 修复(程序记忆) | 180 | 99% | 96% |
1147
- | 宫殿 / 架构决策(语义记忆) | 9999 | ≈100% | ≈100% |
1148
-
1149
- 旧日志的噪音在数天内消退,架构决策永久保留。相同查询,始终得到正确结果。
1150
-
1151
- ### 5. 反馈回路
1152
-
1153
- 系统通过**贝叶斯 Beta 分布**学习什么有用、什么没用——这是从二元观察中估计"真实有用性"的数学最优解(`E[Beta(α,β)] = (pos+1)/(pos+neg+2)`):
1154
-
1155
- ```
1156
- 会话 1: recall("认证设计") → 返回 5 条结果
1157
- Agent 评价: 结果 #1 有用, 结果 #3 没用
1158
- → 存入 feedback-log.json(带查询上下文)
1159
-
1160
- 会话 2: recall("认证模式") → 类似查询
1161
- → 结果 #1: Beta(2,1) → E[U]=0.67 → ×1.33 分数倍增
1162
- → 结果 #3: Beta(1,2) → E[U]=0.33 → ×0.67 分数惩罚
1163
- → 排名变化: 有用的记忆上升,噪音下沉
1164
- ```
1165
-
1166
- 无反馈的条目保持中性(×1.0)。反馈是查询感知的 — 把一条结果标记为"对认证设计没用"不会惩罚它在"数据库设计"中的表现。系统按上下文学习,而非全局惩罚。
1167
-
1168
- ### 复合效应
1006
+ 旧日志噪音数天内消退,架构决策永久保留。
1169
1007
 
1008
+ **复合效应:**
1170
1009
  ```
1171
1010
  会话 1: 保存 3 条记忆(自动命名、索引、创建边)
1172
- 会话 5: recall 浮现会话 1-4 的记忆,反馈优化排名
1173
1011
  会话 10: watch_for 在错误重复之前警告 agent
1174
1012
  会话 20: 感知包含 10 条交叉验证的洞察(从 40+ 条原始观察合并)
1175
1013
  会话 50: Agent 了解你的优先级、盲点和沟通风格
1176
- — 不是因为被告知,而是因为每次纠正都在复合增长
1177
1014
  ```
1178
1015
 
1179
- 每一层放大其他层。自动命名让索引有意义。索引让关联性成为可能。关联性让检索精准。精准检索产生有意义的反馈。反馈让下一次检索更好。循环复合增长。
1180
-
1181
1016
  ---
1182
1017
 
1183
1018
  ## SDK API
1184
1019
 
1185
- `agent-recall-sdk` 提供 `AgentRecall` 类 — 完整记忆系统的编程接口。可用于 LangChain、CrewAI、Vercel AI SDK 或任何自定义 JS/TS 智能体框架。
1186
-
1187
1020
  ```typescript
1188
1021
  import { AgentRecall } from "agent-recall-sdk";
1189
1022
  const ar = new AgentRecall({ project: "my-project" });
@@ -1206,27 +1039,25 @@ const ar = new AgentRecall({ project: "my-project" });
1206
1039
 
1207
1040
  ## CLI 命令
1208
1041
 
1209
- `agent-recall-cli` 提供 `ar` 命令,用于终端工作流和 CI 管道。
1210
-
1211
1042
  ```bash
1212
1043
  # 日志
1213
- ar read [--date YYYY-MM-DD] [--section <name>]
1214
- ar write <content> [--section <name>]
1215
1044
  ar capture <question> <answer> [--tags tag1,tag2]
1045
+ ar read [--date YYYY-MM-DD]
1216
1046
  ar search <query> [--include-palace]
1217
1047
  ar rollup [--min-age-days N] [--dry-run]
1218
1048
 
1219
1049
  # 宫殿
1220
- ar palace read [<room>]
1221
1050
  ar palace write <room> <content> [--importance high|medium|low]
1222
1051
  ar palace walk [--depth identity|active|relevant|full]
1223
1052
  ar palace search <query>
1224
1053
 
1225
1054
  # 感知与洞察
1226
- ar awareness read
1227
1055
  ar awareness update --insight "标题" --evidence "证据" --applies-when kw1,kw2
1228
1056
  ar insight <context> [--limit N]
1229
1057
 
1058
+ # 语义召回配置
1059
+ ar setup supabase [--migrate] [--backfill]
1060
+
1230
1061
  # 全局选项
1231
1062
  --root <path> 存储根目录(默认:~/.agent-recall)
1232
1063
  --project <slug> 项目覆盖
@@ -1246,17 +1077,9 @@ L4: 感知系统 awareness_update 「复合的洞察」
1246
1077
  L5: 洞察索引 recall_insight 「跨项目的经验」
1247
1078
  ```
1248
1079
 
1249
- ### 核心机制
1250
-
1251
1080
  **扇出写入** — 写入一个房间,相关房间通过 `[[wikilinks]]` 自动更新交叉引用。零 LLM 成本。
1252
1081
 
1253
- **显著性评分** — `时效性(0.30) + 访问频率(0.25) + 连接数(0.20) + 紧迫性(0.15) + 重要性(0.10)`。高显著性房间优先展示,低于阈值自动归档。
1254
-
1255
- **复合感知** — `awareness.md` 上限 200 行。新洞察与相似的合并(增强),与不相似的竞争(最低确认次数的被替换)。约束创造压缩,压缩创造复合。
1256
-
1257
- **跨项目洞察召回** — 通过关键词将洞察映射到场景。`recall_insight("构建质量检查")` 返回来自任何项目的相关教训。
1258
-
1259
- **Obsidian 兼容** — YAML frontmatter + `[[wikilinks]]`。将 `palace/` 作为 Obsidian vault 打开即可。零 Obsidian 依赖。
1082
+ **Obsidian 兼容** — YAML frontmatter + `[[wikilinks]]`。将 `palace/` 作为 Obsidian vault 打开即可。
1260
1083
 
1261
1084
  ---
1262
1085
 
@@ -1276,15 +1099,28 @@ L5: 洞察索引 recall_insight 「跨项目的经验」
1276
1099
 
1277
1100
  ---
1278
1101
 
1102
+ ## 实测 Token 节省
1103
+
1104
+ | 场景 | 无 AR | 有 AR | **节省** |
1105
+ |------|:----:|:----:|:------:|
1106
+ | **A: 简单** (2 会话,0 纠正) | 567 | 1,131 | **+99% 纯开销** |
1107
+ | **B: 中等** (5 会话,1 次纠正) | 6,220 | 4,382 | **-30%** |
1108
+ | **C: 复杂** (20 会话,5 次纠正) | 40,910 | 17,520 | **-57%** |
1109
+ | **D: 多 Agent** (3 个 agent × 5 会话) | 20,781 | 13,140 | **-37%** |
1110
+ | **E: Digest 缓存** (重复分析,1 次命中) | ~2,400 | ~400 | **-83%** |
1111
+
1112
+ > **盈亏平衡:~3-4 个会话。** 简单一次性任务,AR 是纯开销。3+ 会话、有纠正、多 agent 的场景,AR 都能回本。
1113
+
1114
+ ---
1115
+
1279
1116
  ## 文档
1280
1117
 
1281
1118
  | 文档 | 说明 |
1282
1119
  |------|------|
1283
- | [智能距离协议](docs/intelligent-distance-protocol.md) | 基础理论 — 人类与 AI 之间的差距是结构性的,如何减少两个物种之间的沟通信息损失 |
1284
- | [评分设计原理](docs/SCORING.md) | 评分系统的工作原理 — RRF、艾宾浩斯、Beta 分布及其修复的 bug |
1285
- | [MCP 适配器规范](docs/mcp-adapter-spec.md) | 基于 AgentRecall 构建适配器的技术规范 |
1286
- | [SDK 设计](docs/sdk-design.md) | SDK 架构设计文档 |
1287
- | [v3.4 升级说明](UPGRADE-v3.4.md) | 周报压缩、宫殿优先冷启动、提升验证 |
1120
+ | **[→ 命令参考](docs/commands.md)** | **`/arstatus`、`/arstart`、`/arsave`、`/arsaveall` 完整指南** |
1121
+ | [智能距离协议](docs/intelligent-distance-protocol.md) | 基础理论 — 人类与 AI 之间的差距是结构性的,如何减少信息损失 |
1122
+ | [评分设计原理](docs/SCORING.md) | RRF、艾宾浩斯、Beta 分布及其修复的 bug |
1123
+ | [v3.4 升级说明](UPGRADE-v3.4.md) | 语义召回、pgvector、10 工具、bootstrap、decisions 房间 |
1288
1124
 
1289
1125
  ---
1290
1126
 
@@ -1294,6 +1130,15 @@ L5: 洞察索引 recall_insight 「跨项目的经验」
1294
1130
 
1295
1131
  - Issues & 反馈:[GitHub Issues](https://github.com/Goldentrii/AgentRecall/issues)
1296
1132
  - 邮箱:[tong.wu@novada.com](mailto:tong.wu@novada.com)
1297
- - 网站:[novada.com](https://www.novada.com)
1298
1133
 
1299
1134
  MIT 许可证。
1135
+
1136
+ ## Star History
1137
+
1138
+ <a href="https://www.star-history.com/?repos=Goldentrii%2FAgentRecall&type=date&legend=top-left">
1139
+ <picture>
1140
+ <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=Goldentrii/AgentRecall&type=date&theme=dark&legend=top-left" />
1141
+ <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=Goldentrii/AgentRecall&type=date&legend=top-left" />
1142
+ <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=Goldentrii/AgentRecall&type=date&legend=top-left" />
1143
+ </picture>
1144
+ </a>