agent-recall-sdk 3.3.28 → 3.4.1
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.
- package/README.md +427 -582
- 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://
|
|
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/
|
|
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-
|
|
20
|
-
<img src="https://img.shields.io/badge/feedback-
|
|
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>
|
|
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="#
|
|
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>
|
|
36
38
|
<a href="#agentrecall中文文档">简介</a> ·
|
|
37
39
|
<a href="#快速开始">安装</a> ·
|
|
38
|
-
<a href="
|
|
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-
|
|
48
|
-
<a href="#arsave-and-
|
|
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
|
-
##
|
|
68
|
+
## Already Using Another Memory System? `/arbootstrap`
|
|
64
69
|
|
|
65
|
-
>
|
|
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
|
-
| **`/
|
|
70
|
-
| **`/arstart`** |
|
|
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
|
-
|
|
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/
|
|
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
|
-
//
|
|
285
|
-
await memory.
|
|
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
|
-
|
|
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
|
-
#
|
|
309
|
-
ar
|
|
427
|
+
# Step 1 — interactive setup wizard
|
|
428
|
+
ar setup supabase
|
|
310
429
|
|
|
311
|
-
#
|
|
312
|
-
ar
|
|
430
|
+
# Step 2 — apply pgvector migration to your Supabase project
|
|
431
|
+
ar setup supabase --migrate
|
|
313
432
|
|
|
314
|
-
#
|
|
315
|
-
|
|
433
|
+
# Step 3 — done. Run /arstart — backfill happens automatically.
|
|
434
|
+
```
|
|
316
435
|
|
|
317
|
-
|
|
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
|
-
|
|
321
|
-
ar insight "building auth middleware"
|
|
438
|
+
### How it works
|
|
322
439
|
|
|
323
|
-
|
|
324
|
-
|
|
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
|
-
|
|
327
|
-
|
|
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
|
-
##
|
|
511
|
+
## 10 MCP Tools
|
|
380
512
|
|
|
381
|
-
AgentRecall exposes
|
|
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.
|
|
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,
|
|
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
|
|
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.
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
|
648
|
+
The `agent-recall-cli` package provides the `ar` command for terminal workflows and CI pipelines.
|
|
576
649
|
|
|
577
650
|
```
|
|
578
|
-
ar v3.
|
|
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
|
-
##
|
|
779
|
+
## Benchmarked Token Savings
|
|
699
780
|
|
|
700
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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:
|
|
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-
|
|
790
|
-
<a href="#arsave-
|
|
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` 和 `/
|
|
860
|
+
## `/arstatus`、`/arsave`、`/arstart` 和 `/arsaveall`
|
|
806
861
|
|
|
807
|
-
>
|
|
862
|
+
> [!IMPORTANT]
|
|
863
|
+
> **每次新会话都先运行 `/arstatus`。** 它会显示你所有项目的状态、待完成的工作、阻塞项,让你用数字选择下一步——无需记住项目名称。没有它,全新的 agent 根本不知道从哪里开始。
|
|
808
864
|
|
|
809
865
|
| 命令 | 时机 | 功能 |
|
|
810
866
|
|------|------|------|
|
|
811
|
-
| **`/
|
|
812
|
-
| **`/arstart`** |
|
|
867
|
+
| ⭐ **`/arstatus`** | **每次会话——先运行这个** | **跨所有项目的状态看板:待办事项、阻塞项、编号选择列表。真正的冷启动。** |
|
|
868
|
+
| **`/arstart`** | 选好项目后 | 加载单个项目的深度上下文:宫殿房间、纠正记录、任务相关召回 |
|
|
869
|
+
| **`/arsave`** | 会话结束时 | 写入日志 + 整合到记忆宫殿 + 更新感知 |
|
|
870
|
+
| **`/arsaveall`** | 一天结束时(多会话) | **一次性批量保存所有并行会话** — 扫描、合并、去重、完成 |
|
|
813
871
|
|
|
814
|
-
|
|
872
|
+
**会话流程:** `/arstatus` → 输入编号 → `/arstart <项目>` → 工作 → `/arsave`。
|
|
815
873
|
|
|
816
|
-
|
|
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
|
-
|
|
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
|
-
|
|
886
|
+
2 ● novada-mcp 2026-04-21
|
|
887
|
+
下一步:修复 novada_search POST /request → 发布 v0.8.0
|
|
840
888
|
|
|
841
|
-
|
|
889
|
+
3 ● prismma-scraper 2026-04-17
|
|
890
|
+
下一步:UI 升级 Option A — 浅色模式 + 3D 视觉
|
|
842
891
|
|
|
843
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
946
|
+
---
|
|
1013
947
|
|
|
1014
|
-
|
|
1015
|
-
npm install agent-recall-sdk
|
|
1016
|
-
```
|
|
948
|
+
## 语义召回 — pgvector (v3.4.0)
|
|
1017
949
|
|
|
1018
|
-
|
|
1019
|
-
|
|
950
|
+
> [!NOTE]
|
|
951
|
+
> **v3.4.0 新功能。** 默认关键词召回无需任何配置。当关键词搜索遇到天花板时——同义词、改写查询、多语言——升级到 Supabase pgvector 后端。
|
|
1020
952
|
|
|
1021
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
1054
|
-
|
|
1055
|
-
|
|
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
|
-
##
|
|
973
|
+
## 10 个 MCP 工具
|
|
1061
974
|
|
|
1062
|
-
AgentRecall
|
|
975
|
+
AgentRecall 目前向 agent 提供 10 个工具。每个工具内部组合多个子系统——agent 不需要了解内部管道。
|
|
1063
976
|
|
|
1064
977
|
| 工具 | 功能 |
|
|
1065
978
|
|------|------|
|
|
1066
|
-
| `session_start` |
|
|
1067
|
-
| `remember` |
|
|
1068
|
-
| `recall` |
|
|
1069
|
-
| `session_end` |
|
|
1070
|
-
| `check` |
|
|
1071
|
-
|
|
1072
|
-
|
|
1073
|
-
|
|
1074
|
-
|
|
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
|
-
|
|
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
|
-
|
|
1108
|
-
|------|---------|-----------|
|
|
1109
|
-
| **宫殿索引** | 房间目录 + 显著性评分 | 扫描约 50 token |
|
|
1110
|
-
| **洞察索引** | 跨项目教训 + 关键词匹配 | 查询约 30 token |
|
|
1111
|
-
| **感知文档** | 200 行复合文档(强制合并) | 约 200 token,但每一行都承载交叉验证的权重 |
|
|
998
|
+
**Ebbinghaus 衰减 `R(t) = e^(−t/S)`:**
|
|
1112
999
|
|
|
1113
|
-
|
|
1000
|
+
| 记忆类型 | S(天) | 1天后 | 1周后 |
|
|
1001
|
+
|----------|---------|-------|-------|
|
|
1002
|
+
| 日志(情景) | 2 | 60% | ~7% |
|
|
1003
|
+
| 知识/Bug修复(程序) | 180 | 99% | 96% |
|
|
1004
|
+
| 宫殿/架构决策(语义) | 9999 | ≈100% | ≈100% |
|
|
1114
1005
|
|
|
1115
|
-
|
|
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
|
-
|
|
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
|
-
| [
|
|
1284
|
-
| [
|
|
1285
|
-
| [
|
|
1286
|
-
| [
|
|
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>
|