claude-recall 0.30.1 → 0.30.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +206 -384
- package/docs/kiro.md +159 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -2,251 +2,165 @@
|
|
|
2
2
|
|
|
3
3
|
### Persistent, local memory for coding agents — learn from every session.
|
|
4
4
|
|
|
5
|
-
Claude Recall
|
|
6
|
-
**the ability to learn from you over time.**
|
|
5
|
+
Coding agents forget everything between sessions. Claude Recall fixes that: it captures your preferences, corrections, project facts, and failures **automatically as you work**, stores them in a local SQLite database, and injects them back into the agent's context in every future session.
|
|
7
6
|
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
Your preferences, project structure, workflows, corrections, and coding style are captured automatically and applied in future sessions — **securely stored on your machine**.
|
|
7
|
+
It works with **Claude Code**, **[Pi](https://github.com/mariozechner/pi)**, and **[Kiro CLI](https://kiro.dev/cli/)** — all three share the same database, so a rule learned in one agent is applied in the others. Everything stays on your machine: no cloud, no telemetry, works offline.
|
|
11
8
|
|
|
12
9
|
---
|
|
13
10
|
|
|
14
|
-
##
|
|
15
|
-
|
|
16
|
-
- **Smart Memory Capture** — LLM-powered classification (via Claude Haiku) detects preferences and corrections from natural language, with silent regex fallback
|
|
17
|
-
- **Project-Scoped Knowledge** — each project gets its own memory namespace; switch projects and the agent switches context automatically
|
|
18
|
-
- **Failure Learning** — captures what failed, why, and what to do instead — so the agent doesn't repeat mistakes
|
|
19
|
-
- **Outcome-Aware Learning** — tracks action outcomes (all tool results, test cycles, user corrections), synthesizes candidate lessons, and promotes validated patterns into active rules automatically
|
|
20
|
-
- **Skill Crystallization** — auto-generates `.claude/skills/auto-*/` files from accumulated memories, using Anthropic's [Agent Skills](https://agentskills.io/) open standard
|
|
21
|
-
- **Rule Hygiene** — token-budgeted `load_rules` payload, citation-aware auto-demotion of rules that never earn citations, and retroactive dedup for near-duplicates
|
|
22
|
-
- **Local-Only** — SQLite on your machine, no telemetry, no cloud, works fully offline
|
|
11
|
+
## What it looks like in practice
|
|
23
12
|
|
|
24
|
-
|
|
13
|
+
**Tuesday — you correct the agent once, in plain language:**
|
|
25
14
|
|
|
26
|
-
|
|
15
|
+
> **You:** use pnpm here, not npm
|
|
27
16
|
|
|
28
|
-
|
|
17
|
+
```text
|
|
18
|
+
📌 Recall: auto-captured correction — Use pnpm, not npm
|
|
19
|
+
```
|
|
29
20
|
|
|
30
|
-
|
|
31
|
-
| --------- | ----------------------- | --------------------------- |
|
|
32
|
-
| Node.js | **20.19+** | required for better-sqlite3 (Node 20+) and chalk 5 (ESM `require()` needs ≥20.19) |
|
|
33
|
-
| OS | macOS / Linux / Windows | WSL supported |
|
|
21
|
+
That one line did everything. A hook classified your prompt with an LLM, decided it was a durable rule (not chit-chat), and stored it locally. No "remember this" incantation, no tool call, no config file to edit.
|
|
34
22
|
|
|
35
|
-
|
|
23
|
+
**Friday — brand-new session, no shared history:**
|
|
36
24
|
|
|
37
|
-
|
|
25
|
+
> **You:** set up a test runner for this project
|
|
26
|
+
>
|
|
27
|
+
> **Agent:** Installing vitest with **pnpm** *(applied from memory: "Use pnpm, not npm")* …
|
|
38
28
|
|
|
39
|
-
|
|
40
|
-
npm install -g claude-recall
|
|
41
|
-
```
|
|
29
|
+
Your rules are injected at session start and again right before each relevant tool call — at the moment of decision, not 50,000 tokens upstream. This works across agents too: correct Claude Code on Tuesday, and Kiro applies it on Friday.
|
|
42
30
|
|
|
43
|
-
|
|
31
|
+
**And you can audit what it knows at any time:**
|
|
44
32
|
|
|
45
33
|
```bash
|
|
46
|
-
claude-recall
|
|
47
|
-
|
|
34
|
+
$ claude-recall search "pnpm"
|
|
35
|
+
🔍 Found 1 memories (showing top 1):
|
|
36
|
+
|
|
37
|
+
1. [correction] Score: 7.9
|
|
38
|
+
Content: {"content":"Use pnpm, not npm","confidence":0.95,"source":"hook-auto-capture",...}
|
|
48
39
|
```
|
|
49
40
|
|
|
50
|
-
|
|
41
|
+
---
|
|
51
42
|
|
|
52
|
-
|
|
43
|
+
## Features
|
|
53
44
|
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
45
|
+
- **Automatic capture** — an LLM classifier detects preferences, corrections, and project facts in your normal prompts (regex fallback when no LLM is available)
|
|
46
|
+
- **Applied where it counts** — rules load at session start *and* are re-surfaced just-in-time before each tool call
|
|
47
|
+
- **Project-scoped** — each project gets its own memory namespace; switch directories and the agent switches context
|
|
48
|
+
- **Learns from failures** — records what broke, why, and what fixed it, so mistakes aren't repeated
|
|
49
|
+
- **Outcome-aware** — tracks whether rules actually help (tool results, test cycles, re-asks) and promotes validated lessons into active rules
|
|
50
|
+
- **Local-only** — one SQLite file on your machine; inspect, export, or delete everything from the CLI
|
|
57
51
|
|
|
58
|
-
|
|
52
|
+
---
|
|
59
53
|
|
|
60
|
-
|
|
54
|
+
## Quick Start
|
|
61
55
|
|
|
62
|
-
|
|
56
|
+
**Requirements:** Node.js **20.19+**, macOS / Linux / Windows (WSL supported).
|
|
63
57
|
|
|
64
|
-
|
|
58
|
+
Install the global binary once per machine:
|
|
65
59
|
|
|
66
60
|
```bash
|
|
67
|
-
|
|
61
|
+
npm install -g claude-recall
|
|
68
62
|
```
|
|
69
63
|
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
### Install for Kiro CLI
|
|
73
|
-
|
|
74
|
-
Requires claude-recall **≥ 0.28.0** (`claude-recall --version` to check; `claude-recall upgrade` to update). Uses the same global binary (install it once per machine as above). Two ways to wire it in — full integration is what most people want.
|
|
64
|
+
> **Do NOT add claude-recall as a project dependency** (`npm install claude-recall` inside a project). All projects share one database, and a stale project-local copy silently shadows your global one. One global binary; per-project *activation* only.
|
|
65
|
+
> Hit `EACCES: permission denied`? See [Upgrade & install troubleshooting](#upgrading) below.
|
|
75
66
|
|
|
76
|
-
|
|
67
|
+
### Claude Code
|
|
77
68
|
|
|
78
|
-
In
|
|
69
|
+
In each project where you want it active:
|
|
79
70
|
|
|
80
71
|
```bash
|
|
81
|
-
claude-recall
|
|
72
|
+
claude-recall setup --install
|
|
73
|
+
claude mcp add claude-recall -- claude-recall mcp start
|
|
82
74
|
```
|
|
83
75
|
|
|
84
|
-
|
|
76
|
+
Restart Claude Code. Ask *"Load my rules"* to verify — Claude should call `load_rules`.
|
|
85
77
|
|
|
86
|
-
|
|
78
|
+
Prefer it available in **every** project? Register the MCP server once at user scope (memories stay isolated per project either way — scoping comes from the working directory, not the install):
|
|
87
79
|
|
|
88
80
|
```bash
|
|
89
|
-
|
|
90
|
-
```
|
|
91
|
-
|
|
92
|
-
and inside the Kiro chat, switch to the agent:
|
|
93
|
-
|
|
94
|
-
```
|
|
95
|
-
/agent swap recall
|
|
81
|
+
claude mcp add --scope user claude-recall -- claude-recall mcp start
|
|
96
82
|
```
|
|
97
83
|
|
|
98
|
-
|
|
84
|
+
Hook-based auto-capture remains a per-project opt-in via `claude-recall setup --install`.
|
|
99
85
|
|
|
100
|
-
|
|
86
|
+
### Pi
|
|
101
87
|
|
|
102
88
|
```bash
|
|
103
|
-
claude-recall
|
|
89
|
+
pi install npm:claude-recall
|
|
104
90
|
```
|
|
105
91
|
|
|
106
|
-
|
|
92
|
+
That's it. Ask Pi to *"Load my rules"* to verify.
|
|
107
93
|
|
|
108
|
-
|
|
94
|
+
### Kiro CLI
|
|
109
95
|
|
|
110
|
-
|
|
96
|
+
Requires claude-recall ≥ 0.28.0. In the project directory, before starting Kiro:
|
|
111
97
|
|
|
112
98
|
```bash
|
|
113
|
-
|
|
114
|
-
kiro
|
|
99
|
+
claude-recall kiro setup # writes a custom agent at .kiro/agents/recall.json
|
|
100
|
+
kiro # then inside the chat: /agent swap recall
|
|
115
101
|
```
|
|
116
102
|
|
|
117
|
-
|
|
103
|
+
Already living in a custom agent of your own? Merge Claude Recall into it instead of swapping (backup written, idempotent, your config preserved):
|
|
118
104
|
|
|
119
105
|
```bash
|
|
120
|
-
claude-recall
|
|
121
|
-
tail -5 ~/.claude-recall/hook-logs/hook-dispatcher.log
|
|
122
|
-
```
|
|
123
|
-
|
|
124
|
-
The log should show a `scope [...] → project=your-project` line; `claude-recall kiro doctor` gives a fuller health report.
|
|
125
|
-
|
|
126
|
-
> **Capture uses Kiro's own LLM — no API key needed.** To decide what's worth remembering, the capture hook classifies each prompt via a headless `kiro-cli chat --no-interactive --model …` call (through a bundled bare `claude-recall-classifier` agent). So natural statements like "my favourite color is green" are captured without any `ANTHROPIC_API_KEY` and without the `store_memory` MCP tool — which matters under enterprise governance that blocks the MCP server. It runs in a detached background worker, so your turn is never blocked; it spends ~0.06 Kiro credits per prompt.
|
|
127
|
-
>
|
|
128
|
-
> **The classifier uses a dedicated, fixed model — not your chat model.** It always runs the model in `CLAUDE_RECALL_KIRO_MODEL` (default `claude-haiku-4.5`, chosen because classification is cheap and high-volume), **independent of your interactive Kiro chat model** (e.g. `auto`). This keeps classification cost predictable no matter what your chat is set to. Set `CLAUDE_RECALL_KIRO_MODEL` to any model from `kiro-cli chat --list-models` to change it. Every successful classification is logged to `~/.claude-recall/hook-logs/kiro-classifier.log` as `classified via kiro-cli (model=…, Kiro credits, no API key)`, so you can always see which model ran.
|
|
129
|
-
>
|
|
130
|
-
> **Under Kiro the included LLM is used first even if you happen to have `ANTHROPIC_API_KEY` set** — so a key exported for other tools won't quietly spend your Anthropic credits. Order: Kiro's LLM → `ANTHROPIC_API_KEY` (if present) → regex; set `CLAUDE_RECALL_PREFER_API_KEY=1` to force your key first (e.g. for a stronger model you pay for). Details in [docs/kiro-llm-capture.md](docs/kiro-llm-capture.md).
|
|
131
|
-
|
|
132
|
-
**Option B — MCP tools only (no hooks, works in Kiro's default agent).**
|
|
133
|
-
|
|
134
|
-
If you don't want a custom agent, register just the MCP server in Kiro's config instead. Create or merge into `.kiro/settings/mcp.json` (project) or `~/.kiro/settings/mcp.json` (all projects):
|
|
135
|
-
|
|
136
|
-
```json
|
|
137
|
-
{
|
|
138
|
-
"mcpServers": {
|
|
139
|
-
"claude-recall": {
|
|
140
|
-
"command": "claude-recall",
|
|
141
|
-
"args": ["mcp", "start"],
|
|
142
|
-
"autoApprove": ["load_rules", "search_memory", "load_checkpoint"]
|
|
143
|
-
}
|
|
144
|
-
}
|
|
145
|
-
}
|
|
106
|
+
claude-recall kiro setup --merge-into <agent-name>
|
|
146
107
|
```
|
|
147
108
|
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
**Not available under Kiro** with either option (Kiro's hooks expose no transcript): transcript-based failure detection and session-end auto-checkpoints.
|
|
151
|
-
|
|
152
|
-
> **Project scoping & `--resume`.** Memories scope to the **working directory Kiro reports for the session** — normally the directory you launched Kiro from. `kiro --resume` resumes the most recent conversation *from the current directory* (it's per-project), so scoping and `--resume` naturally agree. Just remember the snapshot rule above: only conversations **created after** wiring run the hooks.
|
|
109
|
+
> **⚠️ You must start ONE fresh conversation after setup — this is the most common reason "it does nothing."**
|
|
153
110
|
>
|
|
154
|
-
>
|
|
111
|
+
> After `kiro setup` or `--merge-into`, start **one new conversation without `--resume`**:
|
|
155
112
|
>
|
|
156
113
|
> ```bash
|
|
157
|
-
>
|
|
114
|
+
> kiro-cli chat --agent recall # or: --agent <your-agent> if you merged
|
|
158
115
|
> ```
|
|
159
116
|
>
|
|
160
|
-
> `claude-recall
|
|
117
|
+
> Kiro snapshots the agent config at the moment a conversation is *created*. Any conversation that already existed — including one you reach with `--resume` or after restarting Kiro — was snapshotted **before** claude-recall was wired in, so it will **never** run the hooks and capture will silently do nothing. Once you've started that one fresh conversation, every conversation from then on carries the hooks and `--resume` works normally. This is a one-time rollover, once per project.
|
|
161
118
|
>
|
|
162
|
-
>
|
|
163
|
-
|
|
164
|
-
### Shared Database
|
|
165
|
-
|
|
166
|
-
All runtimes (Claude Code, Pi, Kiro CLI) use the same database at `~/.claude-recall/claude-recall.db`, scoped per project by working directory. A correction learned in one agent is available in the others.
|
|
167
|
-
|
|
168
|
-
### Upgrading
|
|
169
|
-
|
|
170
|
-
One command upgrades the shared binary for **all** runtimes (Claude Code, Pi, and Kiro use the same global install):
|
|
171
|
-
|
|
172
|
-
```bash
|
|
173
|
-
claude-recall upgrade
|
|
174
|
-
```
|
|
175
|
-
|
|
176
|
-
It checks the registry, refreshes the global binary, and clears any running MCP servers — they respawn on the next tool call with the new version.
|
|
177
|
-
|
|
178
|
-
Per-runtime notes:
|
|
179
|
-
|
|
180
|
-
- **Claude Code** — nothing else needed; registrations point at the `claude-recall` command, not a pinned path. If the release notes mention new or changed hooks (a `hooksVersion` bump), also re-run `claude-recall setup --install` in each active project — safe any time; a no-op when hooks are already current.
|
|
181
|
-
- **Pi** — run `pi update npm:claude-recall` and restart Pi.
|
|
182
|
-
- **Kiro CLI** — the agent config points at the `claude-recall` command, so the binary upgrade alone applies to hook *behaviour*. But when the release notes change the agent *template* (new hooks, the classifier agent, revised wiring — e.g. the **0.29.x** Kiro-LLM capture), re-run setup once so the agent picks it up: `claude-recall kiro setup --force` for the standalone `recall` agent, or `claude-recall kiro setup --merge-into <agent>` for an agent you merged into. That also writes the `claude-recall-classifier` agent and strips any superseded hooks. Then start one fresh conversation per project (the snapshot rollover above). `claude-recall kiro doctor` confirms the result.
|
|
183
|
-
|
|
184
|
-
> **Claude Code registered before v0.27.x?** Older versions auto-registered the MCP server with an `npx`-based command, which re-resolves the package on every server start and can be shadowed by stale project-local installs. Switch to the direct binary form (run in each affected project):
|
|
119
|
+
> Confirm the wiring is live before you rely on it:
|
|
185
120
|
>
|
|
186
121
|
> ```bash
|
|
187
|
-
> claude
|
|
188
|
-
> claude mcp add claude-recall -- claude-recall mcp start
|
|
122
|
+
> claude-recall kiro doctor # green checks = hooks are active for this project
|
|
189
123
|
> ```
|
|
190
124
|
|
|
191
|
-
|
|
192
|
-
>
|
|
193
|
-
> ```bash
|
|
194
|
-
> claude-recall upgrade
|
|
195
|
-
> ```
|
|
196
|
-
>
|
|
197
|
-
> If `upgrade` itself is the unknown command (pre-0.23.2 install), bootstrap once with `npm install -g claude-recall@latest`.
|
|
125
|
+
**Capture runs on Kiro's own LLM — no API key, no personal subscription.** It classifies each prompt with a dedicated fixed model (default `claude-haiku-4.5`, independent of your chat model) and costs **~0.06 Kiro credits per prompt** — cheap, but note it's *every* prompt, so budget accordingly across a team.
|
|
198
126
|
|
|
199
|
-
|
|
200
|
-
<summary><b>If the install step reports <code>EACCES: permission denied</code></b></summary>
|
|
127
|
+
**What to expect from capture — read this so it doesn't feel broken:**
|
|
201
128
|
|
|
202
|
-
|
|
129
|
+
- **It's silent and asynchronous.** Capture runs in a background worker so it never blocks your turn — which also means there's **no "captured ✓" message** in the Kiro chat. Stating a preference and seeing nothing happen is normal.
|
|
130
|
+
- **It's a best-effort LLM judgement, not a guarantee.** The classifier decides what's a durable rule vs. chit-chat; it won't catch every phrasing, and near-identical wording can occasionally be judged differently. State preferences plainly ("use pnpm here, not npm") for the best hit rate.
|
|
131
|
+
- **There's a ~3s lag.** A preference you just stated isn't queryable for a couple of seconds while the worker finishes.
|
|
203
132
|
|
|
204
|
-
**
|
|
205
|
-
```bash
|
|
206
|
-
sudo npm install -g claude-recall@latest
|
|
207
|
-
```
|
|
133
|
+
**To verify capture actually worked** — from a second terminal (Kiro's chat can't shell out):
|
|
208
134
|
|
|
209
|
-
**Permanent** — move the prefix to a user-owned directory so no global install ever needs sudo again:
|
|
210
135
|
```bash
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
|
|
214
|
-
source ~/.bashrc
|
|
215
|
-
|
|
216
|
-
# Install claude-recall into the new user-owned prefix:
|
|
217
|
-
npm install -g claude-recall@latest
|
|
218
|
-
|
|
219
|
-
# Verify and you're done:
|
|
220
|
-
claude-recall --version
|
|
136
|
+
claude-recall search "pnpm" # did the rule land?
|
|
137
|
+
tail -5 ~/.claude-recall/hook-logs/kiro-classifier.log # what the classifier decided, and which model ran
|
|
221
138
|
```
|
|
222
139
|
|
|
223
|
-
|
|
140
|
+
Or, from **inside the Kiro session**, just ask the agent to recall it (*"what do you remember about my package manager?"*) — it reads the same DB and will surface the stored rule if capture succeeded.
|
|
224
141
|
|
|
225
|
-
|
|
142
|
+
**Everything else Kiro** — MCP-only mode, project scoping and `--resume`, the classifier internals, enterprise-governance notes, troubleshooting: **[docs/kiro.md](docs/kiro.md)**.
|
|
226
143
|
|
|
227
144
|
---
|
|
228
145
|
|
|
229
|
-
## What
|
|
146
|
+
## What happens automatically
|
|
230
147
|
|
|
231
|
-
Once installed, Claude Recall works
|
|
148
|
+
Once installed, Claude Recall works in the background (CC = Claude Code):
|
|
232
149
|
|
|
233
150
|
| When | What happens | CC | Pi | Kiro |
|
|
234
151
|
|---|---|:-:|:-:|:-:|
|
|
235
|
-
| **Session start** | Active rules are
|
|
236
|
-
| **As you
|
|
237
|
-
| **Before each tool call
|
|
238
|
-
| **Tool outcomes** |
|
|
239
|
-
| **
|
|
240
|
-
| **Before context compression** |
|
|
241
|
-
| **After context compression** | Rules are
|
|
242
|
-
| **Sub-agent spawned** |
|
|
243
|
-
| **
|
|
244
|
-
| **
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
Classification and checkpoint extraction use Claude Haiku (via `ANTHROPIC_API_KEY`) with silent regex fallback. No configuration needed.
|
|
248
|
-
|
|
249
|
-
**Next session:** `load_rules` returns everything captured previously — the agent applies your preferences without being told twice.
|
|
152
|
+
| **Session start** | Active rules are injected into the agent's context | ✓ | ✓ | ✓ |
|
|
153
|
+
| **As you type** | Prompts are classified; durable preferences/corrections are stored | ✓ | ✓ | ✓ |
|
|
154
|
+
| **Before each tool call** | Relevant rules are re-surfaced next to the action (just-in-time injection) | ✓ | ✓ | ✓ |
|
|
155
|
+
| **Tool outcomes** | Failures are recorded; Bash failures are paired with their eventual fix | ✓ | ✓ | ✓ |
|
|
156
|
+
| **Re-ask detection** | Frustration signals (*"still broken"*) are recorded as outcome events | ✓ | ✓ | ✓ |
|
|
157
|
+
| **Before context compression** | Important context is captured before the window shrinks | ✓ | ✓ | |
|
|
158
|
+
| **After context compression** | Rules are re-injected into the fresh context | ✓ | | |
|
|
159
|
+
| **Sub-agent spawned** | Rules are injected into the sub-agent; its outcome is captured | ✓ | | |
|
|
160
|
+
| **Session exit** | An auto-checkpoint (`{completed, remaining, blockers}`) is saved for next time | ✓ | ✓ | |
|
|
161
|
+
| **End of session** | Failure patterns become candidate lessons; validated ones are promoted to rules | ✓ | ✓ | |
|
|
162
|
+
|
|
163
|
+
Classification uses an LLM wherever one is available — Claude Code provides `ANTHROPIC_API_KEY` to its hooks; Kiro uses its own included LLM — with silent regex fallback. No configuration needed.
|
|
250
164
|
|
|
251
165
|
```bash
|
|
252
166
|
# Verify it's working
|
|
@@ -256,249 +170,107 @@ claude-recall search "preference"
|
|
|
256
170
|
|
|
257
171
|
---
|
|
258
172
|
|
|
259
|
-
##
|
|
260
|
-
|
|
261
|
-
Claude Recall provides six memory tools (`load_rules`, `store_memory`, `search_memory`, `delete_memory`, `save_checkpoint`, `load_checkpoint`) backed by a local SQLite database with WAL mode, content-hash deduplication, and automatic compaction. The tools are exposed differently depending on the agent:
|
|
262
|
-
|
|
263
|
-
- **Claude Code** — MCP server with four tools and seven prompts, plus file-system hooks for automatic capture
|
|
264
|
-
- **Pi** — native extension with registered tools and event handlers, plus a skill file for behavioral guidance
|
|
265
|
-
|
|
266
|
-
| Tool | Claude Code | Pi |
|
|
267
|
-
| ---- | ----------- | --- |
|
|
268
|
-
| Load rules | `mcp__claude-recall__load_rules` | `recall_load_rules` |
|
|
269
|
-
| Store memory | `mcp__claude-recall__store_memory` | `recall_store_memory` |
|
|
270
|
-
| Search memory | `mcp__claude-recall__search_memory` | `recall_search_memory` |
|
|
271
|
-
| Delete memory | `mcp__claude-recall__delete_memory` | `recall_delete_memory` |
|
|
272
|
-
|
|
273
|
-
### Skills
|
|
274
|
-
|
|
275
|
-
Claude Recall uses skill files to teach agents when and how to use memory tools.
|
|
276
|
-
|
|
277
|
-
**Claude Code** uses Anthropic's [Agent Skills](https://agentskills.io/) open standard:
|
|
278
|
-
|
|
279
|
-
- `.claude/skills/memory-management/SKILL.md` — core skill, guides memory behavior
|
|
280
|
-
- `.claude/skills/auto-*/` — auto-generated, crystallized from accumulated memories
|
|
281
|
-
|
|
282
|
-
See Anthropic's [Agent Skills blog post](https://claude.com/blog/equipping-agents-for-the-real-world-with-agent-skills) for the standard.
|
|
283
|
-
|
|
284
|
-
**Pi** ships a single `skills/memory-management.md` loaded via Pi's package manifest. No setup needed.
|
|
285
|
-
|
|
286
|
-
### Outcome-Aware Learning
|
|
287
|
-
|
|
288
|
-
Claude Recall tracks what happens *after* the agent acts — not just what was said. The pipeline:
|
|
289
|
-
|
|
290
|
-
```
|
|
291
|
-
action → outcome event → episode → candidate lesson → promotion → active rule
|
|
292
|
-
↓
|
|
293
|
-
JIT-injected before next action
|
|
294
|
-
↓
|
|
295
|
-
PostToolUse resolves outcome per rule
|
|
296
|
-
```
|
|
297
|
-
|
|
298
|
-
- **Outcome events** capture results from all tool types (Bash, Edit, Write, MCP), test outcomes, user corrections, and reask signals
|
|
299
|
-
- **Episodes** summarize entire sessions with outcome type, severity, and confidence
|
|
300
|
-
- **Candidate lessons** are extracted from failure patterns — deduplicated by Jaccard similarity
|
|
301
|
-
- **Promotion engine** graduates lessons into active rules after 2+ observations (or immediately for high-severity failures)
|
|
302
|
-
- **Just-in-time rule injection (v0.22.0+)** — active rules are surfaced as a `<system-reminder>` block adjacent to each tool call (Claude Code) or each agent turn (Pi). Each injection is recorded in `rule_injection_events` and resolved with the tool's success/failure outcome by the PostToolUse hook. **This is the meter that measures rule effectiveness in practice.** It replaces the older citation-detection regex (which empirically returned 0 citations across thousands of opportunities — agents don't reliably write `(applied from memory: …)` markers, so the meter never had data to work with).
|
|
303
|
-
- **Per-rule effectiveness data** accumulates over time in `rule_injection_events`. Future releases will use it to deboost rules that are repeatedly injected without correlating to successful tool calls, and to auto-promote rules that are repeatedly injected before failures. As of v0.22.0 the data is being collected; ranking is not yet feeding back from it.
|
|
304
|
-
|
|
305
|
-
---
|
|
306
|
-
|
|
307
|
-
## CLI Reference
|
|
308
|
-
|
|
309
|
-
### Health Check (run these first)
|
|
310
|
-
|
|
311
|
-
```bash
|
|
312
|
-
claude-recall --version # Confirm installed version
|
|
313
|
-
claude-recall status # Installation health: hooks, MCP, DB path, project ID
|
|
314
|
-
claude-recall stats # What's in the DB for this project
|
|
315
|
-
claude-recall stats --global # What's in the DB across ALL projects
|
|
316
|
-
```
|
|
317
|
-
|
|
318
|
-
### Inspecting Memories
|
|
173
|
+
## Everyday commands
|
|
319
174
|
|
|
320
175
|
```bash
|
|
321
|
-
claude-recall
|
|
322
|
-
claude-recall
|
|
323
|
-
claude-recall search "query" --json # Machine-readable output
|
|
324
|
-
claude-recall search "query" --project <id> # Search a specific project
|
|
325
|
-
|
|
326
|
-
claude-recall failures # View failure memories (current project)
|
|
327
|
-
claude-recall failures --limit 20 # Show more
|
|
176
|
+
claude-recall status # Installation health: hooks, MCP, DB path, project ID
|
|
177
|
+
claude-recall stats # What's in the DB for this project (--global for all)
|
|
328
178
|
|
|
179
|
+
claude-recall search "query" # Search this project's memories (--global, --json, --project <id>)
|
|
180
|
+
claude-recall failures # What broke and what fixed it
|
|
329
181
|
claude-recall outcomes # Outcome-aware learning status
|
|
330
|
-
claude-recall outcomes --section lessons # Just candidate lessons
|
|
331
|
-
claude-recall outcomes --section stats # Retrieval/helpfulness stats per memory
|
|
332
|
-
claude-recall outcomes --limit 20 # More items per section
|
|
333
182
|
|
|
334
|
-
claude-recall
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
183
|
+
claude-recall store "content" # Store a memory by hand (-t correction|devops|...)
|
|
184
|
+
claude-recall delete <key> # Delete one memory (keys shown by search)
|
|
185
|
+
claude-recall export backup.json # Export to JSON (import to restore)
|
|
186
|
+
claude-recall clear --force # Wipe this project's memories (auto-backup first)
|
|
338
187
|
|
|
339
|
-
|
|
340
|
-
claude-recall store "content" # Store a memory (default type: preference)
|
|
341
|
-
claude-recall store "content" -t correction # Store with specific type
|
|
342
|
-
claude-recall export backup.json # Export current project's memories to JSON
|
|
343
|
-
claude-recall export backup.json --global # Export ALL projects' memories
|
|
344
|
-
claude-recall import backup.json # Import memories from JSON
|
|
345
|
-
claude-recall clear --force # Delete current project's memories (auto-backup written first)
|
|
346
|
-
claude-recall clear --force --global # Delete ALL projects' memories
|
|
188
|
+
claude-recall upgrade # Update the global binary for all runtimes
|
|
347
189
|
```
|
|
348
190
|
|
|
349
|
-
### Task
|
|
191
|
+
### Task checkpoints
|
|
350
192
|
|
|
351
|
-
Persistent "where I left off" snapshots — one per project,
|
|
193
|
+
Persistent "where I left off" snapshots — one per project, replaced on each save:
|
|
352
194
|
|
|
353
195
|
```bash
|
|
354
|
-
claude-recall checkpoint save
|
|
355
|
-
|
|
356
|
-
--remaining "wire server.js, strip 3GPP URNs" \
|
|
357
|
-
--blockers "none" \
|
|
358
|
-
--notes "see inference/README.md"
|
|
359
|
-
|
|
360
|
-
claude-recall checkpoint load # Show the latest checkpoint
|
|
361
|
-
claude-recall checkpoint load --json # Machine-readable
|
|
362
|
-
claude-recall checkpoint clear # Delete the checkpoint
|
|
196
|
+
claude-recall checkpoint save --completed "API layer" --remaining "wire the UI" --blockers "none"
|
|
197
|
+
claude-recall checkpoint load
|
|
363
198
|
```
|
|
364
199
|
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
#### Auto-checkpoint on session exit (v0.21.2+)
|
|
368
|
-
|
|
369
|
-
Manual `checkpoint save` is the explicit path. **Auto-checkpoint** is the safety net: when a session ends, the most recent task is extracted into a checkpoint automatically so the next session can resume.
|
|
370
|
-
|
|
371
|
-
**When it fires:**
|
|
372
|
-
|
|
373
|
-
- **Pi** — every `session_shutdown` event. **This is the only way to recover context in Pi: there is no `pi --resume` equivalent.**
|
|
374
|
-
- **Claude Code** — voluntary `SessionEnd` reasons (`clear`, `prompt_input_exit`, `logout`). Skips `bypass_permissions_disabled` and `other` (system-driven exits, not user intent). Useful if you exit and start fresh instead of using `claude --resume`.
|
|
375
|
-
|
|
376
|
-
**Behavior (both runtimes):**
|
|
377
|
-
|
|
378
|
-
- Uses Haiku to extract `{completed, remaining, blockers}` from the most recent task in the transcript
|
|
379
|
-
- **Quality gate**: refuses to save if the LLM detects the task was already complete (e.g., agent said "Done.", user said "thanks"). **Manual checkpoints are never overwritten with garbage** — an empty checkpoint is far better than a fabricated one
|
|
380
|
-
- **Tagged**: auto-saved checkpoints include `[auto-saved on <pi|cc> session exit at <iso-timestamp>]` in their notes field
|
|
381
|
-
- **Requires `ANTHROPIC_API_KEY`**. Without it, no auto-checkpoint is saved and manual `checkpoint save` still works
|
|
382
|
-
|
|
383
|
-
**Disable:**
|
|
384
|
-
|
|
385
|
-
- **Claude Code**: remove the `SessionEnd` block from `.claude/settings.json`
|
|
386
|
-
- **Pi**: no per-project disable flag yet — [open an issue](https://github.com/raoulbia-ai/claude-recall/issues) if you need one
|
|
200
|
+
Auto-checkpoints are also saved on session exit in Claude Code and Pi (Pi has no `--resume`, so this is its main recovery path). Extraction uses Haiku via `ANTHROPIC_API_KEY`; without a key, only manual checkpoints work. A quality gate refuses to overwrite a manual checkpoint with a fabricated one when the task was already complete.
|
|
387
201
|
|
|
388
202
|
### Troubleshooting
|
|
389
203
|
|
|
390
204
|
```bash
|
|
391
|
-
#
|
|
392
|
-
|
|
393
|
-
claude-recall
|
|
394
|
-
claude-recall
|
|
395
|
-
|
|
396
|
-
#
|
|
397
|
-
claude-recall status # Shows hook registration status
|
|
398
|
-
claude-recall hooks check # Verify hook files exist and are valid
|
|
205
|
+
claude-recall status # Are hooks + MCP registered? Which project is this?
|
|
206
|
+
claude-recall hooks check # Do the hook files exist and validate?
|
|
207
|
+
claude-recall mcp status # Is the MCP server running? (mcp ps lists all)
|
|
208
|
+
claude-recall project show # Which project ID does this directory map to?
|
|
209
|
+
claude-recall repair # Fix broken hook paths (--dry-run to preview)
|
|
210
|
+
claude-recall mcp cleanup --all # Stop stale MCP servers
|
|
399
211
|
|
|
400
|
-
#
|
|
401
|
-
claude-recall
|
|
402
|
-
claude-recall mcp ps # List all running servers
|
|
212
|
+
# What did the hooks actually do?
|
|
213
|
+
tail -20 ~/.claude-recall/hook-logs/hook-dispatcher.log
|
|
403
214
|
|
|
404
|
-
# "
|
|
405
|
-
claude-recall
|
|
406
|
-
claude-recall project list # All registered projects
|
|
407
|
-
|
|
408
|
-
# "Why do I see memories from other projects?"
|
|
409
|
-
claude-recall search "query" # Scoped to current project (default)
|
|
410
|
-
claude-recall search "query" --global # Explicitly cross-project
|
|
411
|
-
|
|
412
|
-
# "How do I check what the DB actually contains?"
|
|
413
|
-
sqlite3 ~/.claude-recall/claude-recall.db "SELECT type, COUNT(*) FROM memories GROUP BY type"
|
|
414
|
-
sqlite3 ~/.claude-recall/claude-recall.db "SELECT type, COUNT(*) FROM memories WHERE project_id = '<id>' GROUP BY type"
|
|
415
|
-
|
|
416
|
-
# "Hook logs — what did the hooks actually do?"
|
|
417
|
-
tail -20 ~/.claude-recall/hook-logs/tool-outcome-watcher.log
|
|
418
|
-
tail -20 ~/.claude-recall/hook-logs/memory-stop.log
|
|
419
|
-
tail -20 ~/.claude-recall/hook-logs/correction-detector.log
|
|
420
|
-
|
|
421
|
-
# "Something is broken, start fresh"
|
|
422
|
-
claude-recall repair # Conservative: fix broken hook paths in settings.json (preserves your customizations)
|
|
423
|
-
claude-recall repair --dry-run # Preview what repair would change
|
|
424
|
-
claude-recall repair --reinstall-hooks # Opinionated: rewrite entire hook block from current template
|
|
425
|
-
claude-recall setup --install # Reinstall skills + hooks
|
|
426
|
-
claude-recall mcp cleanup --all # Stop all stale MCP servers
|
|
215
|
+
# "error: unknown command '<x>'" → your binary predates the feature:
|
|
216
|
+
claude-recall upgrade
|
|
427
217
|
```
|
|
428
218
|
|
|
429
219
|
<details>
|
|
430
|
-
<summary>All commands</summary>
|
|
220
|
+
<summary><b>All commands</b></summary>
|
|
431
221
|
|
|
432
222
|
```bash
|
|
433
223
|
# ── Setup & Diagnostics ─────────────────────────────────────────────
|
|
434
224
|
claude-recall setup # Show activation instructions
|
|
435
225
|
claude-recall setup --install # Install skills + hooks (Claude Code, current project)
|
|
436
|
-
claude-recall kiro setup # Write Kiro custom agent (
|
|
437
|
-
claude-recall kiro setup --merge-into <agent> # Merge
|
|
226
|
+
claude-recall kiro setup # Write Kiro custom agent (--global for all projects)
|
|
227
|
+
claude-recall kiro setup --merge-into <agent> # Merge into an existing Kiro agent
|
|
228
|
+
claude-recall kiro doctor # Kiro integration health report
|
|
438
229
|
claude-recall upgrade # One-shot upgrade: global binary + clear stale MCP servers
|
|
439
230
|
claude-recall status # Installation and system status
|
|
440
|
-
claude-recall repair # Fix broken claude-recall hook paths (
|
|
441
|
-
claude-recall repair --auto # Non-interactive; apply safe fixes without prompting
|
|
231
|
+
claude-recall repair # Fix broken claude-recall hook paths (preserves your customizations)
|
|
232
|
+
claude-recall repair --auto # Non-interactive; apply safe fixes without prompting
|
|
442
233
|
claude-recall repair --dry-run # Report what would change without writing
|
|
443
|
-
claude-recall repair --scope user|project|all # Scope the scan
|
|
234
|
+
claude-recall repair --scope user|project|all # Scope the scan (default: all)
|
|
444
235
|
claude-recall repair --reinstall-hooks # Opinionated: rewrite entire hook block from current template
|
|
445
236
|
claude-recall hooks check # Verify hook files exist and are valid
|
|
446
237
|
claude-recall hooks test-enforcement # Test if search enforcer hook works
|
|
447
238
|
|
|
448
239
|
# ── Memory ───────────────────────────────────────────────────────────
|
|
449
|
-
claude-recall stats # Memory statistics (
|
|
450
|
-
claude-recall
|
|
451
|
-
claude-recall search "query" # Search memories (current project)
|
|
452
|
-
claude-recall search "query" --global # Search memories (all projects)
|
|
453
|
-
claude-recall search "query" --json # Output as JSON
|
|
454
|
-
claude-recall search "query" --project <id> # Search specific project
|
|
240
|
+
claude-recall stats # Memory statistics (--global for all projects)
|
|
241
|
+
claude-recall search "query" # Search memories (--global, --json, --project <id>)
|
|
455
242
|
claude-recall store "content" # Store memory directly
|
|
456
|
-
claude-recall store "content" -t <type> #
|
|
457
|
-
claude-recall export backup.json # Export current project
|
|
458
|
-
claude-recall export backup.json --global # Export all projects
|
|
243
|
+
claude-recall store "content" -t <type> # Type: preference, correction, failure, devops, project-knowledge
|
|
244
|
+
claude-recall export backup.json # Export current project (--global for all)
|
|
459
245
|
claude-recall import backup.json # Import memories from JSON
|
|
460
246
|
claude-recall delete <key> # Delete one memory by key (get keys from `search`)
|
|
461
|
-
claude-recall clear --force # Clear current project (auto-backup written first)
|
|
462
|
-
claude-recall
|
|
463
|
-
claude-recall
|
|
464
|
-
claude-recall failures --limit 20 # Limit results
|
|
465
|
-
claude-recall outcomes # Outcome-aware learning status
|
|
466
|
-
claude-recall outcomes --section lessons # Just candidate lessons
|
|
467
|
-
claude-recall outcomes --section stats # Retrieval/helpfulness stats
|
|
468
|
-
claude-recall outcomes --limit 20 # More items per section
|
|
247
|
+
claude-recall clear --force # Clear current project (--global for all; auto-backup written first)
|
|
248
|
+
claude-recall failures # View failure memories (--limit N)
|
|
249
|
+
claude-recall outcomes # Outcome-aware learning status (--section lessons|stats, --limit N)
|
|
469
250
|
claude-recall monitor # Memory search monitoring stats
|
|
470
251
|
|
|
471
252
|
# ── Rule Hygiene ─────────────────────────────────────────────────────
|
|
472
|
-
claude-recall rules demote [--dry-run]
|
|
473
|
-
claude-recall rules demote --min-loads 20
|
|
474
|
-
claude-recall rules
|
|
475
|
-
claude-recall rules
|
|
476
|
-
claude-recall rules dedup [--dry-run] # Collapse near-duplicate rules (Jaccard >= threshold)
|
|
477
|
-
claude-recall rules dedup --threshold 0.8 # Stricter similarity (default 0.65)
|
|
478
|
-
|
|
479
|
-
# ── Cleanup (destructive — always --dry-run first) ─────────────────
|
|
480
|
-
claude-recall cleanup test-pollution [--dry-run] # Delete legacy test-fixture rows
|
|
253
|
+
claude-recall rules demote [--dry-run] # Demote rules loaded >=N times but never cited
|
|
254
|
+
claude-recall rules demote --min-loads 20 --min-age-days 7 # Tune thresholds
|
|
255
|
+
claude-recall rules promote <id> # Restore an auto-demoted or auto-deduped rule
|
|
256
|
+
claude-recall rules dedup [--dry-run] # Collapse near-duplicate rules (--threshold 0.8 for stricter)
|
|
481
257
|
|
|
482
258
|
# ── Task Checkpoints ────────────────────────────────────────────────
|
|
483
|
-
claude-recall checkpoint save --completed <text> --remaining <text> [--blockers <text>] [--notes <text>]
|
|
484
|
-
claude-recall checkpoint load [--
|
|
485
|
-
claude-recall checkpoint clear
|
|
259
|
+
claude-recall checkpoint save --completed <text> --remaining <text> [--blockers <text>] [--notes <text>]
|
|
260
|
+
claude-recall checkpoint load [--json]
|
|
261
|
+
claude-recall checkpoint clear
|
|
486
262
|
|
|
487
263
|
# ── Skills ───────────────────────────────────────────────────────────
|
|
488
|
-
claude-recall skills generate # Generate skills from memories
|
|
489
|
-
claude-recall skills generate --dry-run # Preview without writing
|
|
490
|
-
claude-recall skills generate --force # Regenerate even if unchanged
|
|
264
|
+
claude-recall skills generate # Generate skills from memories (--dry-run, --force)
|
|
491
265
|
claude-recall skills list # List generated skills
|
|
492
266
|
claude-recall skills clean --force # Remove all auto-generated skills
|
|
493
267
|
|
|
494
268
|
# ── MCP Server ───────────────────────────────────────────────────────
|
|
495
269
|
claude-recall mcp status # Current project's server status
|
|
496
270
|
claude-recall mcp ps # List all running servers
|
|
497
|
-
claude-recall mcp stop
|
|
498
|
-
claude-recall mcp
|
|
499
|
-
claude-recall mcp
|
|
500
|
-
claude-recall mcp cleanup # Remove stale PID files
|
|
501
|
-
claude-recall mcp cleanup --all # Stop all servers
|
|
271
|
+
claude-recall mcp stop [--force] # Stop server
|
|
272
|
+
claude-recall mcp restart # Stop server (Claude Code respawns it next session)
|
|
273
|
+
claude-recall mcp cleanup [--all] # Remove stale PID files / stop all servers
|
|
502
274
|
|
|
503
275
|
# ── Project ──────────────────────────────────────────────────────────
|
|
504
276
|
claude-recall project show # Current project info
|
|
@@ -508,8 +280,8 @@ claude-recall project unregister [id] # Unregister a project
|
|
|
508
280
|
claude-recall project clean # Remove stale registry entries
|
|
509
281
|
|
|
510
282
|
# ── Database Maintenance ─────────────────────────────────────────────
|
|
511
|
-
claude-recall compact # Dedup + prune
|
|
512
|
-
claude-recall
|
|
283
|
+
claude-recall compact # Dedup + prune + VACUUM (--dry-run to preview; also runs on MCP boot)
|
|
284
|
+
claude-recall cleanup test-pollution [--dry-run] # Delete legacy test-fixture rows
|
|
513
285
|
|
|
514
286
|
# ── Auto-Capture Hooks (run automatically, registered via setup --install) ──
|
|
515
287
|
claude-recall hook run correction-detector # UserPromptSubmit hook
|
|
@@ -522,46 +294,86 @@ claude-recall hook run memory-sync # Stop + PreCompact hook (syncs rul
|
|
|
522
294
|
|
|
523
295
|
---
|
|
524
296
|
|
|
525
|
-
##
|
|
297
|
+
## How it works
|
|
298
|
+
|
|
299
|
+
Six memory tools (`load_rules`, `store_memory`, `search_memory`, `delete_memory`, `save_checkpoint`, `load_checkpoint`) backed by one local SQLite database (`~/.claude-recall/claude-recall.db`, WAL mode, content-hash dedup, auto-compaction). Exposure per agent:
|
|
526
300
|
|
|
527
|
-
|
|
301
|
+
- **Claude Code** — MCP server (`mcp__claude-recall__*` tools) + file-system hooks for automatic capture
|
|
302
|
+
- **Pi** — native extension (`recall_*` tools) + event handlers
|
|
303
|
+
- **Kiro CLI** — custom agent bundling the MCP server + Kiro hooks ([details](docs/kiro.md))
|
|
528
304
|
|
|
529
|
-
|
|
305
|
+
**Skills.** Claude Recall teaches agents *when* to use memory via skill files — Anthropic's [Agent Skills](https://agentskills.io/) standard for Claude Code (`.claude/skills/memory-management/`, plus auto-generated `.claude/skills/auto-*/` crystallized from accumulated memories), and a bundled skill file for Pi.
|
|
530
306
|
|
|
531
|
-
|
|
307
|
+
**Outcome-aware learning.** Claude Recall tracks what happens *after* the agent acts:
|
|
308
|
+
|
|
309
|
+
```
|
|
310
|
+
action → outcome event → episode → candidate lesson → promotion → active rule
|
|
311
|
+
↓
|
|
312
|
+
JIT-injected before the next action
|
|
313
|
+
↓
|
|
314
|
+
outcome resolved per injected rule
|
|
315
|
+
```
|
|
316
|
+
|
|
317
|
+
Failures become candidate lessons (deduplicated by similarity); lessons seen 2+ times (or once, if severe) are promoted to active rules; every just-in-time injection is recorded and resolved against the tool's outcome, building per-rule effectiveness data over time.
|
|
532
318
|
|
|
533
319
|
---
|
|
534
320
|
|
|
535
|
-
##
|
|
321
|
+
## Upgrading
|
|
536
322
|
|
|
537
|
-
|
|
538
|
-
- No prompts, code, or memory content is transmitted
|
|
539
|
-
- Full transparency via CLI (`stats`, `search`, `export`)
|
|
540
|
-
- Never stores secrets (API keys, passwords, tokens)
|
|
323
|
+
One command upgrades the shared binary for **all** runtimes:
|
|
541
324
|
|
|
542
|
-
|
|
325
|
+
```bash
|
|
326
|
+
claude-recall upgrade
|
|
327
|
+
```
|
|
543
328
|
|
|
544
|
-
|
|
329
|
+
It checks the registry, refreshes the global binary, and clears any running MCP servers — they respawn on the next tool call with the new version.
|
|
330
|
+
|
|
331
|
+
Per-runtime notes:
|
|
332
|
+
|
|
333
|
+
- **Claude Code** — nothing else needed. If the release notes mention new or changed hooks, also re-run `claude-recall setup --install` in each active project (safe any time; a no-op when current).
|
|
334
|
+
- **Pi** — run `pi update npm:claude-recall` and restart Pi.
|
|
335
|
+
- **Kiro CLI** — the binary upgrade covers hook behaviour; when release notes change the agent *template*, re-run `kiro setup` once and start one fresh conversation — see [docs/kiro.md](docs/kiro.md#upgrading).
|
|
545
336
|
|
|
546
337
|
<details>
|
|
547
|
-
<summary>
|
|
338
|
+
<summary><b>Install & upgrade troubleshooting</b> (EACCES, unknown command, pre-0.27 registrations)</summary>
|
|
339
|
+
|
|
340
|
+
**`EACCES: permission denied`** — your global npm prefix is root-owned (common when node came from `apt`). Quick fix: `sudo npm install -g claude-recall@latest`. Permanent fix — move the prefix to a user-owned directory so global installs never need sudo again:
|
|
341
|
+
|
|
342
|
+
```bash
|
|
343
|
+
mkdir -p ~/.npm-global
|
|
344
|
+
npm config set prefix ~/.npm-global
|
|
345
|
+
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
|
|
346
|
+
source ~/.bashrc
|
|
347
|
+
npm install -g claude-recall@latest
|
|
348
|
+
claude-recall --version
|
|
349
|
+
```
|
|
548
350
|
|
|
549
|
-
|
|
351
|
+
**`error: unknown command '<anything>'`** — your installed binary is older than the docs you're reading (`kiro` needs ≥ 0.28.0, `compact` ≥ 0.26.0, `upgrade` ≥ 0.23.2). Run `claude-recall upgrade`; if `upgrade` itself is unknown, bootstrap with `npm install -g claude-recall@latest`.
|
|
352
|
+
|
|
353
|
+
**Claude Code registered before v0.27.x?** Older versions auto-registered the MCP server with an `npx`-based command, which can be shadowed by stale project-local installs. Switch to the direct binary form (run in each affected project):
|
|
550
354
|
|
|
551
355
|
```bash
|
|
552
|
-
|
|
553
|
-
|
|
356
|
+
claude mcp remove claude-recall
|
|
357
|
+
claude mcp add claude-recall -- claude-recall mcp start
|
|
554
358
|
```
|
|
555
359
|
|
|
556
|
-
|
|
360
|
+
**WSL: "invalid ELF header"** — mixed Windows/WSL `node_modules`. Use the global install (the default) and verify the binary resolves to a Linux path: `which claude-recall` should show `/home/<user>/...`, not a Windows path. Global installation does not affect project scoping.
|
|
557
361
|
|
|
558
362
|
</details>
|
|
559
363
|
|
|
560
364
|
---
|
|
561
365
|
|
|
562
|
-
##
|
|
366
|
+
## Project scoping
|
|
367
|
+
|
|
368
|
+
Each project gets isolated memory. The **project ID** is derived from the working directory the agent reports; universal memories (no project scope) are available everywhere. Switching projects switches memory automatically — no configuration.
|
|
563
369
|
|
|
564
|
-
|
|
370
|
+
To pin one logical project across several directories (worktrees, subrepos), set `CLAUDE_RECALL_PROJECT_ID`. Details: [docs/project-scoping.md](docs/project-scoping.md).
|
|
371
|
+
|
|
372
|
+
---
|
|
373
|
+
|
|
374
|
+
## Configuration
|
|
375
|
+
|
|
376
|
+
Defaults work out of the box; tune via environment variables as needed.
|
|
565
377
|
|
|
566
378
|
| Variable | Default | Effect |
|
|
567
379
|
| ---------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------- |
|
|
@@ -579,14 +391,24 @@ Runtime behavior can be tuned via environment variables. Defaults are chosen so
|
|
|
579
391
|
| `CLAUDE_RECALL_MAX_MEMORIES` | `10000` | Memory-row soft cap. |
|
|
580
392
|
| `CLAUDE_RECALL_ENFORCE_MODE` | `on` | Set to `off` to bypass the search-enforcer hook. |
|
|
581
393
|
| `CLAUDE_RECALL_LLM_TIMEOUT_MS` | `5000` | Timeout for hook-context LLM calls (classification, hindsight hints). Hooks fall back to regex when it fires. |
|
|
582
|
-
| `CLAUDE_RECALL_STOP_DEBOUNCE_MS` | `300000` | Debounce for the heavy Stop-hook pipeline (episodes, session extraction, promotion).
|
|
583
|
-
| `CLAUDE_RECALL_PROJECT_ID` | *(cwd)* | Pin the project scope to a fixed id, overriding working-directory detection.
|
|
394
|
+
| `CLAUDE_RECALL_STOP_DEBOUNCE_MS` | `300000` | Debounce for the heavy Stop-hook pipeline (episodes, session extraction, promotion). `0` disables. |
|
|
395
|
+
| `CLAUDE_RECALL_PROJECT_ID` | *(cwd)* | Pin the project scope to a fixed id, overriding working-directory detection. |
|
|
396
|
+
|
|
397
|
+
---
|
|
398
|
+
|
|
399
|
+
## Security & privacy
|
|
400
|
+
|
|
401
|
+
- SQLite memory never leaves your machine — no prompts, code, or memory content is transmitted
|
|
402
|
+
- Full transparency via CLI (`stats`, `search`, `export`)
|
|
403
|
+
- Never stores secrets (API keys, passwords, tokens)
|
|
404
|
+
|
|
405
|
+
Details in [docs/security.md](docs/security.md).
|
|
584
406
|
|
|
585
407
|
---
|
|
586
408
|
|
|
587
|
-
## Development &
|
|
409
|
+
## Development & contributions
|
|
588
410
|
|
|
589
|
-
PRs welcome
|
|
411
|
+
PRs welcome.
|
|
590
412
|
|
|
591
413
|
```bash
|
|
592
414
|
npm run build # Compile TypeScript
|
package/docs/kiro.md
ADDED
|
@@ -0,0 +1,159 @@
|
|
|
1
|
+
# Claude Recall + Kiro CLI — the full guide
|
|
2
|
+
|
|
3
|
+
Everything about running Claude Recall under [Kiro CLI](https://kiro.dev/cli/): setup options, the one-time conversation rollover, how capture works without an API key, project scoping, and troubleshooting.
|
|
4
|
+
|
|
5
|
+
Requires claude-recall **≥ 0.28.0** (`claude-recall --version` to check; `claude-recall upgrade` to update). Kiro uses the same global binary and the same database as Claude Code and Pi — a memory captured in one agent is available in the others.
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## Setup Option A — full integration (recommended)
|
|
10
|
+
|
|
11
|
+
Memory **plus** hooks (auto-capture, rule injection) via a Kiro custom agent.
|
|
12
|
+
|
|
13
|
+
In your shell, in the project directory, **before** starting Kiro:
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
claude-recall kiro setup
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
This writes a Kiro custom agent at `.kiro/agents/recall.json` (use `--global` for `~/.kiro/agents` so it's available in every project). It does **not** touch your `mcp.json` — the agent config carries its own `mcpServers` entry for claude-recall, so no separate MCP registration is needed. It also sets `includeMcpJson: true`, so any other servers you have in `mcp.json` keep working alongside it.
|
|
20
|
+
|
|
21
|
+
Then start Kiro from your shell:
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
kiro
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
and inside the Kiro chat, switch to the agent:
|
|
28
|
+
|
|
29
|
+
```
|
|
30
|
+
/agent swap recall
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
You get: active rules injected into context automatically at agent start (no tool call needed), just-in-time rule injection before each tool call, automatic capture of corrections/preferences from your prompts, tool-outcome tracking with Bash fix-pairing, and the full MCP tool surface (read-only tools pre-approved).
|
|
34
|
+
|
|
35
|
+
### Merging into an agent you already use
|
|
36
|
+
|
|
37
|
+
Don't want to swap agents? Merge Claude Recall into your own:
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
claude-recall kiro setup --merge-into <agent-name>
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
This finds the agent config (workspace `.kiro/agents/` first, then `~/.kiro/agents/`; `--global` to target the global one directly), writes a timestamped backup, and appends the claude-recall pieces — MCP server, pre-approved read-only tools, and the four hooks — while leaving your own config untouched. It only rewrites claude-recall's own entries: superseded ones from an older version are swapped for the current wiring (any unrelated hook you have on the same event is preserved). Idempotent: on an already-current agent, re-running changes nothing. If the agent restricts tools with an explicit list, `@claude-recall` is added to it.
|
|
44
|
+
|
|
45
|
+
---
|
|
46
|
+
|
|
47
|
+
## The one-time conversation rollover
|
|
48
|
+
|
|
49
|
+
> **⚠️ After `kiro setup` or `--merge-into`: start ONE fresh conversation per project (no `--resume`).**
|
|
50
|
+
|
|
51
|
+
Kiro snapshots the agent config into each conversation **at creation** — `--resume` restores that snapshot and ignores agent-config changes made since. So conversations created *before* you wired claude-recall will **never** run its hooks, no matter how often you resume them or restart Kiro. Start one fresh conversation after wiring; every conversation created from then on carries the hooks, **including when resumed** (`--resume` works normally afterwards — this is a one-time rollover per project).
|
|
52
|
+
|
|
53
|
+
The rollover, concretely (add your usual flags, e.g. `--classic`, `--trust-all-tools`):
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
cd ~/path/to/your-project
|
|
57
|
+
kiro-cli chat --agent <your-agent>
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
In that session state something memorable (e.g. `recall the deploy pipeline uses helm`), exit, then verify it was captured:
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
claude-recall search "helm"
|
|
64
|
+
tail -5 ~/.claude-recall/hook-logs/hook-dispatcher.log
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
The log should show a `scope [...] → project=your-project` line; `claude-recall kiro doctor` gives a fuller health report.
|
|
68
|
+
|
|
69
|
+
---
|
|
70
|
+
|
|
71
|
+
## How capture works under Kiro — no API key needed
|
|
72
|
+
|
|
73
|
+
To decide what's worth remembering, the capture hook classifies each prompt via a headless `kiro-cli chat --no-interactive --model …` call (through a bundled bare `claude-recall-classifier` agent). So natural statements like "my favourite color is green" are captured without any `ANTHROPIC_API_KEY` and without the `store_memory` MCP tool — which matters under enterprise governance that blocks the MCP server. It runs in a detached background worker, so your turn is never blocked; it spends ~0.06 Kiro credits per prompt.
|
|
74
|
+
|
|
75
|
+
**The classifier uses a dedicated, fixed model — not your chat model.** It always runs the model in `CLAUDE_RECALL_KIRO_MODEL` (default `claude-haiku-4.5`, chosen because classification is cheap and high-volume), **independent of your interactive Kiro chat model** (e.g. `auto`). This keeps classification cost predictable no matter what your chat is set to. Set `CLAUDE_RECALL_KIRO_MODEL` to any model from `kiro-cli chat --list-models` to change it. Every successful classification is logged to `~/.claude-recall/hook-logs/kiro-classifier.log` as `classified via kiro-cli (model=…, Kiro credits, no API key)`, so you can always see which model ran.
|
|
76
|
+
|
|
77
|
+
**Under Kiro the included LLM is used first even if you happen to have `ANTHROPIC_API_KEY` set** — so a key exported for other tools won't quietly spend your Anthropic credits. Order: Kiro's LLM → `ANTHROPIC_API_KEY` (if present) → regex; set `CLAUDE_RECALL_PREFER_API_KEY=1` to force your key first (e.g. for a stronger model you pay for).
|
|
78
|
+
|
|
79
|
+
Design details, latency measurements, and output-parsing internals: [kiro-llm-capture.md](kiro-llm-capture.md).
|
|
80
|
+
|
|
81
|
+
---
|
|
82
|
+
|
|
83
|
+
## Setup Option B — MCP tools only (no hooks)
|
|
84
|
+
|
|
85
|
+
Works in Kiro's default agent; nothing happens automatically. Register just the MCP server in Kiro's config — create or merge into `.kiro/settings/mcp.json` (project) or `~/.kiro/settings/mcp.json` (all projects):
|
|
86
|
+
|
|
87
|
+
```json
|
|
88
|
+
{
|
|
89
|
+
"mcpServers": {
|
|
90
|
+
"claude-recall": {
|
|
91
|
+
"command": "claude-recall",
|
|
92
|
+
"args": ["mcp", "start"],
|
|
93
|
+
"autoApprove": ["load_rules", "search_memory", "load_checkpoint"]
|
|
94
|
+
}
|
|
95
|
+
}
|
|
96
|
+
}
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
With Option B the agent has the memory tools (`load_rules`, `store_memory`, `search_memory`, checkpoints) but no rules at session start and no auto-capture. Ask it to *"load my rules"*.
|
|
100
|
+
|
|
101
|
+
---
|
|
102
|
+
|
|
103
|
+
## Project scoping and `--resume`
|
|
104
|
+
|
|
105
|
+
Memories scope to the **working directory Kiro reports for the session** — normally the directory you launched Kiro from. `kiro --resume` resumes the most recent conversation *from the current directory* (it's per-project), so scoping and `--resume` naturally agree. Just remember the snapshot rule above: only conversations **created after** wiring run the hooks.
|
|
106
|
+
|
|
107
|
+
To force a fixed project id regardless of directory, pin it with `CLAUDE_RECALL_PROJECT_ID`. A per-project shell alias makes it seamless:
|
|
108
|
+
|
|
109
|
+
```bash
|
|
110
|
+
alias kiro-myproj='CLAUDE_RECALL_PROJECT_ID=my-project kiro-cli chat --agent <your-agent> --resume'
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
`claude-recall kiro doctor` always prints the resolved project (and whether it's pinned) so you can confirm where memories are landing before trusting it.
|
|
114
|
+
|
|
115
|
+
---
|
|
116
|
+
|
|
117
|
+
## Enterprise governance
|
|
118
|
+
|
|
119
|
+
Under enterprise governance that restricts MCP to a trusted registry, Kiro drops the claude-recall MCP server — so the agent may say it "has no memory tools." Ignore that: **the hooks capture and inject against the local DB regardless.** The agent is told this at session start and will confirm it's remembering; only the on-demand tools (the agent calling `search_memory` itself) need an admin to allowlist claude-recall.
|
|
120
|
+
|
|
121
|
+
---
|
|
122
|
+
|
|
123
|
+
## What's not available under Kiro
|
|
124
|
+
|
|
125
|
+
Kiro's hooks expose no transcript, so two features are off with either setup option:
|
|
126
|
+
|
|
127
|
+
- transcript-based failure detection
|
|
128
|
+
- session-end auto-checkpoints (existing checkpoints are still surfaced at agent start)
|
|
129
|
+
|
|
130
|
+
---
|
|
131
|
+
|
|
132
|
+
## Upgrading
|
|
133
|
+
|
|
134
|
+
`claude-recall upgrade` refreshes the shared global binary, which is all hook *behaviour* needs — the agent config points at the `claude-recall` command, not a pinned path.
|
|
135
|
+
|
|
136
|
+
But when release notes change the agent *template* (new hooks, the classifier agent, revised wiring — e.g. the **0.29.x** Kiro-LLM capture), re-run setup once so the agent picks it up:
|
|
137
|
+
|
|
138
|
+
- `claude-recall kiro setup --force` for the standalone `recall` agent, or
|
|
139
|
+
- `claude-recall kiro setup --merge-into <agent>` for an agent you merged into.
|
|
140
|
+
|
|
141
|
+
That also writes the `claude-recall-classifier` agent and strips any superseded hooks. Then start one fresh conversation per project (the snapshot rollover above). `claude-recall kiro doctor` confirms the result.
|
|
142
|
+
|
|
143
|
+
---
|
|
144
|
+
|
|
145
|
+
## Troubleshooting
|
|
146
|
+
|
|
147
|
+
```bash
|
|
148
|
+
claude-recall kiro doctor # full health report: agent config, hooks, classifier, project scope
|
|
149
|
+
claude-recall search "something you just said" # did capture land?
|
|
150
|
+
tail -5 ~/.claude-recall/hook-logs/hook-dispatcher.log # which hooks fired, which project
|
|
151
|
+
tail -5 ~/.claude-recall/hook-logs/kiro-classifier.log # which LLM classified (model, credits)
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
Common cases:
|
|
155
|
+
|
|
156
|
+
- **Hooks never fire** → you're in a conversation created before wiring; do the [rollover](#the-one-time-conversation-rollover).
|
|
157
|
+
- **Nothing captured from a natural statement** → check `kiro-classifier.log`; if it shows `kiro-cli error: ENOENT`, `kiro-cli` isn't on the hook's `PATH` and capture fell back to regex.
|
|
158
|
+
- **Agent says it has no memory tools** → see [Enterprise governance](#enterprise-governance); capture still works.
|
|
159
|
+
- **Memories landing in the wrong project** → `claude-recall kiro doctor` shows the resolved project id; pin with `CLAUDE_RECALL_PROJECT_ID` if needed.
|
package/package.json
CHANGED