claude-db 0.9.1 → 0.10.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +236 -0
- package/README.md +74 -113
- package/dist/capture/flush.d.ts +1 -0
- package/dist/capture/flush.js +4 -3
- package/dist/capture/git.js +2 -1
- package/dist/capture/index.d.ts +5 -1
- package/dist/capture/index.js +4 -1
- package/dist/capture/manual.js +1 -1
- package/dist/capture/progress.js +1 -0
- package/dist/capture/redact.d.ts +1 -0
- package/dist/capture/redact.js +17 -0
- package/dist/capture/reingest.d.ts +19 -0
- package/dist/capture/reingest.js +56 -0
- package/dist/capture/scrub.d.ts +11 -0
- package/dist/capture/scrub.js +48 -0
- package/dist/capture/summarize.js +3 -9
- package/dist/capture/transcript.d.ts +1 -0
- package/dist/capture/transcript.js +12 -3
- package/dist/capture/turn-extractor.d.ts +0 -1
- package/dist/capture/turn-extractor.js +10 -19
- package/dist/cli/commands/adoption.js +3 -3
- package/dist/cli/commands/distill.d.ts +1 -0
- package/dist/cli/commands/distill.js +67 -0
- package/dist/cli/commands/doctor.js +11 -3
- package/dist/cli/commands/insight.js +13 -4
- package/dist/cli/commands/maintain.d.ts +2 -1
- package/dist/cli/commands/maintain.js +53 -17
- package/dist/cli/commands/pick.d.ts +3 -0
- package/dist/cli/commands/pick.js +25 -0
- package/dist/cli/commands/setup.js +11 -2
- package/dist/cli/commands/sync.js +73 -12
- package/dist/cli/commands/transfer.d.ts +0 -5
- package/dist/cli/commands/transfer.js +1 -24
- package/dist/cli/commands/use.js +1 -1
- package/dist/cli/commands/view.js +30 -28
- package/dist/cli/index.js +13 -2
- package/dist/cli/install.d.ts +2 -0
- package/dist/cli/install.js +44 -21
- package/dist/cli/instructions.js +4 -2
- package/dist/cli/refresh.js +5 -1
- package/dist/cli/usage.js +4 -0
- package/dist/config/dir.d.ts +1 -0
- package/dist/config/dir.js +3 -0
- package/dist/config/index.d.ts +1 -1
- package/dist/config/index.js +1 -1
- package/dist/config/load.d.ts +4 -1
- package/dist/config/load.js +30 -13
- package/dist/config/schema.d.ts +19 -0
- package/dist/config/schema.js +17 -2
- package/dist/embed/index.d.ts +1 -1
- package/dist/embed/index.js +1 -1
- package/dist/embed/local.js +2 -1
- package/dist/facts/budget.d.ts +4 -0
- package/dist/facts/budget.js +12 -0
- package/dist/facts/claude-memory.d.ts +19 -0
- package/dist/facts/claude-memory.js +100 -0
- package/dist/facts/distill.d.ts +25 -0
- package/dist/facts/distill.js +141 -0
- package/dist/facts/model.d.ts +28 -0
- package/dist/facts/model.js +82 -0
- package/dist/facts/notice.d.ts +2 -0
- package/dist/facts/notice.js +22 -0
- package/dist/facts/ops.d.ts +23 -0
- package/dist/facts/ops.js +91 -0
- package/dist/facts/render.d.ts +4 -0
- package/dist/facts/render.js +13 -0
- package/dist/facts/start.d.ts +6 -0
- package/dist/facts/start.js +57 -0
- package/dist/graph/index.d.ts +2 -6
- package/dist/graph/index.js +2 -3
- package/dist/graph/languages/basic.js +1 -1
- package/dist/graph/languages/index.d.ts +1 -1
- package/dist/graph/parser.js +1 -1
- package/dist/graph/query/index.d.ts +0 -2
- package/dist/graph/query/index.js +0 -1
- package/dist/graph/scan/extract.js +1 -1
- package/dist/graph/scan/files.js +1 -1
- package/dist/graph/scan/index.d.ts +1 -2
- package/dist/graph/scan/index.js +1 -1
- package/dist/hooks/background.d.ts +3 -0
- package/dist/hooks/background.js +43 -0
- package/dist/hooks/compact.d.ts +8 -0
- package/dist/hooks/compact.js +42 -0
- package/dist/hooks/payload.d.ts +3 -0
- package/dist/hooks/payload.js +18 -1
- package/dist/hooks/pick-deliver.d.ts +2 -0
- package/dist/hooks/pick-deliver.js +16 -0
- package/dist/hooks/prompt-recall.d.ts +21 -0
- package/dist/hooks/prompt-recall.js +36 -0
- package/dist/hooks/relevance.d.ts +11 -3
- package/dist/hooks/relevance.js +56 -26
- package/dist/hooks/session-end.js +7 -1
- package/dist/hooks/session-start.js +31 -59
- package/dist/hooks/shown.d.ts +1 -0
- package/dist/hooks/shown.js +5 -2
- package/dist/hooks/start-legacy.d.ts +6 -0
- package/dist/hooks/start-legacy.js +47 -0
- package/dist/hooks/user-prompt.js +29 -25
- package/dist/mcp/server.js +13 -1
- package/dist/pick/pending.d.ts +17 -0
- package/dist/pick/pending.js +106 -0
- package/dist/pick/prompt.d.ts +14 -0
- package/dist/pick/prompt.js +80 -0
- package/dist/pick/run.d.ts +22 -0
- package/dist/pick/run.js +36 -0
- package/dist/pick/worker.d.ts +2 -0
- package/dist/pick/worker.js +32 -0
- package/dist/store/adapter.d.ts +1 -0
- package/dist/store/each.d.ts +5 -0
- package/dist/store/each.js +25 -0
- package/dist/store/mongo/docs.d.ts +2 -0
- package/dist/store/mongo/docs.js +4 -0
- package/dist/store/mongo/driver.js +3 -2
- package/dist/store/mongo/filters.d.ts +1 -0
- package/dist/store/mongo/filters.js +8 -0
- package/dist/store/mongo/index.d.ts +1 -0
- package/dist/store/mongo/index.js +5 -2
- package/dist/store/mongo/observations.d.ts +2 -1
- package/dist/store/mongo/observations.js +11 -1
- package/dist/store/mongo/search.js +12 -3
- package/dist/store/mongo/sessions.js +7 -1
- package/dist/store/mongo/vectorSearch.js +9 -11
- package/dist/store/postgres/driver.js +3 -2
- package/dist/store/postgres/filters.js +5 -0
- package/dist/store/postgres/index.d.ts +1 -0
- package/dist/store/postgres/index.js +3 -0
- package/dist/store/postgres/meta.js +2 -1
- package/dist/store/postgres/observations.d.ts +1 -0
- package/dist/store/postgres/observations.js +14 -3
- package/dist/store/postgres/rows.js +4 -0
- package/dist/store/postgres/schema.d.ts +2 -2
- package/dist/store/postgres/schema.js +4 -1
- package/dist/store/postgres/sessions.js +14 -7
- package/dist/store/session-time.d.ts +2 -0
- package/dist/store/session-time.js +5 -0
- package/dist/store/sqlite/filters.js +5 -0
- package/dist/store/sqlite/index.d.ts +1 -0
- package/dist/store/sqlite/index.js +23 -4
- package/dist/store/sqlite/observations.d.ts +1 -0
- package/dist/store/sqlite/observations.js +14 -1
- package/dist/store/sqlite/rows.js +4 -0
- package/dist/store/sqlite/schema.sql +3 -1
- package/dist/store/sqlite/search.js +7 -3
- package/dist/store/sqlite/sessions.js +13 -8
- package/dist/types.d.ts +5 -1
- package/dist/usages/find.js +5 -3
- package/dist/usages/index.d.ts +0 -1
- package/dist/util/claude-cli.d.ts +6 -0
- package/dist/util/claude-cli.js +38 -0
- package/dist/util/daily-budget.d.ts +7 -0
- package/dist/util/daily-budget.js +38 -0
- package/dist/util/day.d.ts +1 -0
- package/dist/util/day.js +11 -0
- package/dist/util/job-lock.d.ts +4 -0
- package/dist/util/job-lock.js +56 -0
- package/dist/util/prompt.d.ts +5 -0
- package/dist/util/prompt.js +31 -0
- package/docs/how-it-works.md +69 -3
- package/docs/setup-guide.md +339 -0
- package/docs/with-and-without.md +43 -36
- package/package.json +23 -7
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,241 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.10.0
|
|
4
|
+
|
|
5
|
+
### Changed
|
|
6
|
+
|
|
7
|
+
- **Claude Haiku picks the memory shown with a prompt.** Search finds the ten
|
|
8
|
+
closest memories from other chats. If one shares two content words with the
|
|
9
|
+
prompt, Haiku reads them with the prompt and the end of Claude's previous
|
|
10
|
+
reply, and picks at most two, each with one sentence it must copy from the
|
|
11
|
+
memory; the code checks the sentence is there. The pick runs in the
|
|
12
|
+
background and reaches Claude with its first tool call, so typing is never
|
|
13
|
+
held up. Each line reads `- Oct 1: asked "<earlier question>": <copied
|
|
14
|
+
sentence> (id)`. Replaying the same 300 real prompts with old and new side by
|
|
15
|
+
side: 61% to 65% of shown memories judged useful on the final run of the
|
|
16
|
+
shipped code (70% on the labels the picks were studied with) against 23%, and
|
|
17
|
+
memory on 30% of prompts instead of 56%. Nothing from the current chat is
|
|
18
|
+
shown back to it.
|
|
19
|
+
|
|
20
|
+
- **At most 150 picks a day.** A failed call pauses picking for an hour.
|
|
21
|
+
Without Haiku (off, over the limit, or paused) only a strong word match is
|
|
22
|
+
shown: the closest memory, if it shares four content words with the prompt.
|
|
23
|
+
`claude-db pick [on|off]` turns it off or shows today's count, and `status`
|
|
24
|
+
reports it. Saved configs still on earlier defaults (`promptResults: 4`,
|
|
25
|
+
`minOverlap: 1`, or the 0.9 `promptResults: 3`) move to two memories; values
|
|
26
|
+
you changed are kept.
|
|
27
|
+
|
|
28
|
+
- **Prompts nobody typed get no memory.** Subagent reports, task
|
|
29
|
+
notifications, slash commands and local command output matched on noise,
|
|
30
|
+
useful once in eleven. Image paths are stripped before searching, since their
|
|
31
|
+
path words matched other image prompts and nothing else.
|
|
32
|
+
|
|
33
|
+
- **The recall cost is measured, not assumed.** `bench:ab` priced recall with
|
|
34
|
+
a fixed 180 tokens. It now replays real chats through the prompt hook
|
|
35
|
+
(`--recall-from <project>`) and runs this build rather than whatever
|
|
36
|
+
`claude-db` is on `PATH`, with Haiku picking as it ships (`--no-pick` for
|
|
37
|
+
words only). Measured on 300 prompts: ~20 tokens a prompt, with nothing
|
|
38
|
+
injected on 69% of them, so one lookup pays for 34 prompts of recall.
|
|
39
|
+
|
|
40
|
+
The old figures used the assumed 180 tokens a prompt. Recall now costs about
|
|
41
|
+
a ninth of that, and one lookup saves 685 tokens (1,338 by hand against 653
|
|
42
|
+
with it) instead of 597 (1,115 against 518):
|
|
43
|
+
|
|
44
|
+
| A session of | Recall cost, before | Recall cost, now | Lookups to break even, before | Lookups to break even, now |
|
|
45
|
+
| ------------ | ------------------: | ---------------: | ----------------------------: | -------------------------: |
|
|
46
|
+
| 1 prompt | 180 | 20 | 0.3 | 0.0 |
|
|
47
|
+
| 5 prompts | 900 | 101 | 1.5 | 0.1 |
|
|
48
|
+
| 10 prompts | 1,800 | 202 | 3.0 | 0.3 |
|
|
49
|
+
| 20 prompts | 3,600 | 405 | 6.0 | 0.6 |
|
|
50
|
+
| 60 prompts | 10,800 | 1,214 | 18.1 | 1.8 |
|
|
51
|
+
|
|
52
|
+
### Added
|
|
53
|
+
|
|
54
|
+
- **Chats become facts.** When a chat ends, one Claude Haiku call reads its
|
|
55
|
+
saved rows and the facts already known, and writes back short rules,
|
|
56
|
+
decisions with their reasons, dead ends, to-dos and lasting facts. Each has a
|
|
57
|
+
stable key, so a later chat updates it in place, and Haiku retires a fact the
|
|
58
|
+
chat shows is no longer true. The start of a chat shows them as about you,
|
|
59
|
+
this project, and where you stopped (`- Decided (Oct 5): ...`), and `search`
|
|
60
|
+
finds them. Above a prompt, picks come from earlier chats: offered to Haiku,
|
|
61
|
+
facts were useful 60% of the time against 69% for chat rows. On by default,
|
|
62
|
+
through your own Claude
|
|
63
|
+
Code login, in the background: at most 30 calls a day, a day's pause after a
|
|
64
|
+
failed call, a long chat read in windows of about 40,000 characters, and
|
|
65
|
+
older chats from the last 90 days turned into facts newest first.
|
|
66
|
+
`claude-db distill [on|off]` turns it off or shows what it has done, and the
|
|
67
|
+
first session after updating says so once.
|
|
68
|
+
|
|
69
|
+
- **Only a rule follows you everywhere.** A rule about how you work is filed
|
|
70
|
+
under your git email and recalled in every project, and never reaches a
|
|
71
|
+
teammate on a shared database. Everything else stays in its project, whatever
|
|
72
|
+
scope the model asked for: on a real database it filed career details as
|
|
73
|
+
facts about the user.
|
|
74
|
+
|
|
75
|
+
- **Claude Code's own memory files are imported as facts,** at no AI cost, kept
|
|
76
|
+
current as the files change and retired when one is deleted. On the machine
|
|
77
|
+
where Claude already reads them they are not repeated.
|
|
78
|
+
|
|
79
|
+
- **A setup guide,** `docs/setup-guide.md`, ships with the package: requirements,
|
|
80
|
+
install, how to check it works, how to give a fresh install a head start, the
|
|
81
|
+
habits and settings that change results most, what each Haiku feature sends
|
|
82
|
+
and costs, teams, upkeep and troubleshooting.
|
|
83
|
+
|
|
84
|
+
- **Existing installs get the new tool-call hook on their own.** The session
|
|
85
|
+
start refresh that already kept the skill and instructions current now also
|
|
86
|
+
adds missing claude-db hooks, only in settings files that already point at
|
|
87
|
+
the same copy of claude-db. No reinstall is needed after updating.
|
|
88
|
+
|
|
89
|
+
- **`status` reports facts and how many chats are still waiting.**
|
|
90
|
+
|
|
91
|
+
- **`/compact` no longer loses the chat's own work.** The start hook sees
|
|
92
|
+
`source: compact`, saves the latest turns, and puts back what the chat decided
|
|
93
|
+
and left uncommitted under "Earlier in this chat". What the chat had been
|
|
94
|
+
shown before is forgotten, since compaction just dropped it.
|
|
95
|
+
|
|
96
|
+
- **MCP server instructions.** A short note on what `<memory>` lines are and
|
|
97
|
+
when to search, which Claude Code adds to the system prompt for global and
|
|
98
|
+
project installs alike.
|
|
99
|
+
|
|
100
|
+
- **`npm run bench:inject`** replays a project's prompts in time order through
|
|
101
|
+
the hook's own code and reports how many got memory, how much came from the
|
|
102
|
+
same chat, the cost per prompt, and with `--judge` how much was useful, as a
|
|
103
|
+
range over two Haiku passes.
|
|
104
|
+
|
|
105
|
+
### Development
|
|
106
|
+
|
|
107
|
+
- **ESLint with type-aware rules, knip, c8, publint and arethetypeswrong.**
|
|
108
|
+
`npm run lint` runs the house rules and ESLint, `npm run knip` finds unused
|
|
109
|
+
code and packages, `npm run coverage` measures the suite, and
|
|
110
|
+
`npm run check:package` checks the packed tarball and its types. CI runs all
|
|
111
|
+
of them, and CodeQL scans every pull request. Fixing what they found removed
|
|
112
|
+
about a hundred unused imports, typed JSON that was `any`, and kept the cause
|
|
113
|
+
on rethrown errors.
|
|
114
|
+
|
|
115
|
+
- **Test fixtures cannot hold real secrets or personal paths, and the isolated
|
|
116
|
+
test scripts cannot touch your real home.** `npm run lint` now also runs
|
|
117
|
+
`check:fixtures`, which fails on token-like strings, known key prefixes and
|
|
118
|
+
personal home paths in tracked files. `npm run check:fixtures -- --local`
|
|
119
|
+
also compares docs and tests with your own saved memory and Claude Code
|
|
120
|
+
chats and lists any six-word run they share, so private text is caught
|
|
121
|
+
before a push. The scripts under `scripts/unit/isolated` now refuse to run
|
|
122
|
+
unless `runIsolated` started them in a temporary home: run by hand, they
|
|
123
|
+
used the real home and database.
|
|
124
|
+
|
|
125
|
+
- **The plan, the results and every finding from this work are in one document,**
|
|
126
|
+
`docs/memory-improvements.md`, dated 2026-10-06.
|
|
127
|
+
|
|
128
|
+
- **The MCP tools, the end-of-chat hook and the CLI are tested end to end,**
|
|
129
|
+
through the real server, hook and binary in a temporary home: install,
|
|
130
|
+
status, doctor, uninstall, remember, search, forget, export, import, reset,
|
|
131
|
+
prune, stats, projects, flush, view, pick and use.
|
|
132
|
+
|
|
133
|
+
- **`npm audit` is clean.** Five advisories in packages the MCP SDK pulls in
|
|
134
|
+
were patched within their existing ranges.
|
|
135
|
+
|
|
136
|
+
### Fixed
|
|
137
|
+
|
|
138
|
+
- **The usefulness judge in `bench:inject` was close to chance.** It graded 20
|
|
139
|
+
items from different prompts per call and answered by position, so one slip
|
|
140
|
+
shifted every answer after it; its two passes agreed at kappa 0.14. It now
|
|
141
|
+
grades one prompt per call, labels every candidate by id without knowing
|
|
142
|
+
which were shown, sees the end of the previous reply, uses Sonnet by default,
|
|
143
|
+
and prints the agreement (kappa 0.80 on 2,521 pairs). Usefulness figures in
|
|
144
|
+
this release were re-measured with it.
|
|
145
|
+
|
|
146
|
+
- **Secrets written as `NAME=value` are redacted, including in memory already
|
|
147
|
+
saved.** Redaction caught a value after a name like `token` or `password`
|
|
148
|
+
only in quotes, so a pasted `GITHUB_TOKEN=...` or `DATABASE_PASSWORD=...` was
|
|
149
|
+
stored as typed. Unquoted values are now redacted too, when they have a
|
|
150
|
+
letter and are 8 or more characters, so `MAX_TOKENS=4096` is left alone. The
|
|
151
|
+
same redaction runs on memory text sent to Haiku and on every line shown with
|
|
152
|
+
a prompt. Memory saved earlier is cleaned once, in the background, on the
|
|
153
|
+
first session after updating, for each database; a cleaned chat summary is
|
|
154
|
+
marked newer so `sync` carries it. `claude-db redact` runs the same clean-up
|
|
155
|
+
on demand.
|
|
156
|
+
|
|
157
|
+
- **The real minimum is Node 22.16, and it is now enforced.** claude-db said
|
|
158
|
+
22.5, and its install check let 22.5 through, but `node:sqlite` needs a flag
|
|
159
|
+
before 22.13 and has no full-text search (FTS5) before 22.16, so the default
|
|
160
|
+
database failed on every version below 22.16. Checked on real Node 22.5.1,
|
|
161
|
+
22.12, 22.13, 22.15 and 22.16 binaries. The install check, `engines`, the docs
|
|
162
|
+
and CI now say 22.16, CI tests 22.16 itself, and an older Node now gets a
|
|
163
|
+
plain message instead of `no such module: fts5`.
|
|
164
|
+
|
|
165
|
+
- **`install --project` warns about `.mcp.json` when there is no `.gitignore`.**
|
|
166
|
+
It stayed quiet exactly when nothing kept the file out of a commit.
|
|
167
|
+
|
|
168
|
+
- **The driver install command is right for a global install.** The error and
|
|
169
|
+
four docs said `npm install pg` or `npm install mongodb`, which a globally
|
|
170
|
+
installed claude-db does not see. They now say `npm install -g pg` and
|
|
171
|
+
`npm install -g mongodb`, checked against a packed copy installed into a
|
|
172
|
+
throwaway prefix. The install page also named the wrong hooks and skill path.
|
|
173
|
+
|
|
174
|
+
- **`claude-db view` no longer crashes when loading fails.** It sent the
|
|
175
|
+
success header before loading the data, so a failure tried to send a second
|
|
176
|
+
header and the unhandled rejection stopped the viewer. It now builds the whole
|
|
177
|
+
response first.
|
|
178
|
+
|
|
179
|
+
- **A deleted source could still ship as compiled output.** The build never
|
|
180
|
+
cleared `dist/`, so a file removed from `src/` stayed in the package. The
|
|
181
|
+
build now removes compiled files whose source is gone.
|
|
182
|
+
|
|
183
|
+
- **Two store tests passed without testing anything.** `createStore` was never
|
|
184
|
+
imported, so the scheme routing checks caught their own `ReferenceError` and
|
|
185
|
+
passed. They now import it, and the unknown-scheme check requires the real
|
|
186
|
+
message.
|
|
187
|
+
|
|
188
|
+
- **`npm run lint` checks new files too,** not only files git already tracks.
|
|
189
|
+
|
|
190
|
+
- **`sync` now keeps the newer chat summary.** Chats record when their summary
|
|
191
|
+
was written, so a summary rebuilt on one side, or cleared on purpose, wins over
|
|
192
|
+
an older copy, and a chat already turned into facts is marked so on both
|
|
193
|
+
sides.
|
|
194
|
+
|
|
195
|
+
- **The privacy notes were out of date.** They said nothing leaves your machine
|
|
196
|
+
and that a configured database is the only network traffic; the daily update
|
|
197
|
+
check already contacted the npm registry. They now list every outside call and
|
|
198
|
+
how to turn each one off.
|
|
199
|
+
|
|
200
|
+
- **VS Code's notes about the open file no longer count as part of a prompt.**
|
|
201
|
+
|
|
202
|
+
- **A pasted image cost the user's own words.** Claude Code stores an image, a
|
|
203
|
+
skill's instructions and a subagent report as separate hidden messages after
|
|
204
|
+
the typed one, and capture started a new turn at each. The work was filed
|
|
205
|
+
under `Asked: [Image: source: ...]` and the request itself was dropped: 141 of
|
|
206
|
+
551 rows in one real database. Hidden messages and task notifications no
|
|
207
|
+
longer start a turn, saved text has image paths removed and slash commands
|
|
208
|
+
read as `/name args`, and ids still come from the raw prompt so re-ingesting
|
|
209
|
+
updates rows in place.
|
|
210
|
+
|
|
211
|
+
- **Memory saved under the old rules is repaired once, in the background.** The
|
|
212
|
+
first session after updating runs `claude-db flush --repair`: every chat that
|
|
213
|
+
already has memory and whose transcript is still on disk is re-saved, and rows
|
|
214
|
+
it no longer produces are marked `replaced`. They stay in the database, and in
|
|
215
|
+
export and sync, but leave search, the timeline, `view` and `stats`. On the
|
|
216
|
+
database above: 140 rows replaced, 109 lost requests recovered, nothing else
|
|
217
|
+
touched. Chats Claude Code has already deleted keep their rows as they are.
|
|
218
|
+
|
|
219
|
+
- **`sync` carries status across.** It only copied rows the other side lacked,
|
|
220
|
+
so work closed or replaced on one machine stayed open on the other. Status now
|
|
221
|
+
moves forward on both sides, open to done to replaced, never back.
|
|
222
|
+
|
|
223
|
+
- **AI summaries never ran in VS Code,** which does not put `claude` on `PATH`.
|
|
224
|
+
Headless calls now use the running binary first. They also waited 3 seconds
|
|
225
|
+
for stdin on every call (8.5s down to 5.1s), and were saved as chats that
|
|
226
|
+
showed up in `/resume`; both are fixed, with a retry for older CLIs that do
|
|
227
|
+
not know `--no-session-persistence`.
|
|
228
|
+
|
|
229
|
+
- **`fatal: not a git repository` leaked from the hooks** in a folder that is
|
|
230
|
+
not a git repo.
|
|
231
|
+
|
|
232
|
+
- **Code blocks on the docs site showed a white scrollbar in dark mode.** The
|
|
233
|
+
page never told the browser its colour scheme, so wide code blocks, the home
|
|
234
|
+
demo and the command boxes drew the default light scrollbar over a dark
|
|
235
|
+
surface. The page now sets `color-scheme` for both themes, so the table and
|
|
236
|
+
sidebar scrollbars follow the theme too, and those three dark surfaces use a
|
|
237
|
+
thin scrollbar that matches them.
|
|
238
|
+
|
|
3
239
|
## 0.9.1
|
|
4
240
|
|
|
5
241
|
### Fixed
|
package/README.md
CHANGED
|
@@ -14,24 +14,24 @@
|
|
|
14
14
|
|
|
15
15
|
## Every session starts from zero
|
|
16
16
|
|
|
17
|
-
You spent an hour yesterday explaining why the store
|
|
18
|
-
approach you
|
|
19
|
-
|
|
17
|
+
You spent an hour yesterday explaining why the store has three adapters, which
|
|
18
|
+
approach you tried and dropped, and why one function must not be touched. Today
|
|
19
|
+
Claude knows none of it, so you explain it again.
|
|
20
20
|
|
|
21
|
-
claude-db
|
|
22
|
-
|
|
21
|
+
claude-db gives Claude a memory that lasts, and a map of your code so it stops
|
|
22
|
+
working out what calls what from scratch.
|
|
23
23
|
|
|
24
|
-
|
|
25
|
-
$ claude-db search "why does capture read the transcript"
|
|
24
|
+
## What you get
|
|
26
25
|
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
26
|
+
- **A memory that carries over.** When a chat ends, its decisions, dead ends and
|
|
27
|
+
rules are saved as short facts, and the next chat starts by seeing them.
|
|
28
|
+
- **The right memory with each prompt.** Claude Haiku picks the one or two
|
|
29
|
+
earlier memories that fit what you just asked. That costs about 20 tokens a
|
|
30
|
+
prompt on average, and nothing on 69% of prompts.
|
|
31
|
+
- **A code graph.** Who defines or calls a symbol, answered in one call: 2.0x
|
|
32
|
+
cheaper than grep and reading files, measured on eight real symbols.
|
|
33
|
+
- **Your own database.** SQLite by default, or Postgres or MongoDB to share
|
|
34
|
+
memory across machines. No cloud, no subscription.
|
|
35
35
|
|
|
36
36
|
## Install
|
|
37
37
|
|
|
@@ -42,134 +42,95 @@ cd your-project
|
|
|
42
42
|
claude-db install --project
|
|
43
43
|
```
|
|
44
44
|
|
|
45
|
-
Restart Claude Code.
|
|
46
|
-
|
|
45
|
+
Restart Claude Code. Capture and recall are hooks, so there is nothing else to
|
|
46
|
+
run.
|
|
47
47
|
|
|
48
|
-
`--project`
|
|
49
|
-
|
|
50
|
-
|
|
48
|
+
`--project` limits it to this repo instead of every project on the machine. Add
|
|
49
|
+
`.mcp.json` to your `.gitignore`, since it holds a path that only exists on your
|
|
50
|
+
machine.
|
|
51
51
|
|
|
52
|
-
|
|
52
|
+
A fresh install has no history yet. `claude-db scan` builds the code graph, and
|
|
53
|
+
the `/cdb-scan` skill maps an existing codebase into memory, so search has
|
|
54
|
+
something to find on day one. The [setup guide](./docs/setup-guide.md) covers
|
|
55
|
+
the settings and habits that give the best results.
|
|
53
56
|
|
|
54
|
-
|
|
57
|
+
## Commands
|
|
55
58
|
|
|
56
|
-
|
|
57
|
-
claude-db scan
|
|
58
|
-
```
|
|
59
|
+
`cdb` is a shorter alias for all of them.
|
|
59
60
|
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
61
|
+
| Command | What it does |
|
|
62
|
+
| ------------------------------- | ----------------------------------------------------- |
|
|
63
|
+
| `claude-db install [--project]` | Register the hooks and the MCP server |
|
|
64
|
+
| `claude-db status` | Is it wired up, and when did it last record anything |
|
|
65
|
+
| `claude-db doctor [--deep]` | Show the resolved config; `--deep` tests a round trip |
|
|
66
|
+
| `claude-db scan` | Build the code graph for this repo |
|
|
67
|
+
| `claude-db use <url>` | Switch database and verify it |
|
|
68
|
+
| `claude-db distill [on\|off]` | Turn chats into facts with Haiku |
|
|
69
|
+
| `claude-db pick [on\|off]` | Let Haiku pick the memory shown with each prompt |
|
|
70
|
+
| `claude-db view` | See this project's memory in the browser |
|
|
63
71
|
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
twenty more — is read by pattern, which finds declarations and name-matched
|
|
67
|
-
references tagged `INFERRED`. Nothing else to install either way.
|
|
72
|
+
Every other command, including `search`, `remember`, `sync` and `export`, is in
|
|
73
|
+
the [CLI reference](https://claude-db.vercel.app/docs/cli).
|
|
68
74
|
|
|
69
75
|
## Use another database
|
|
70
76
|
|
|
71
|
-
SQLite by default, at `~/.claude-memory/memory.db`. No setup, no network. Point
|
|
72
|
-
it elsewhere to share memory across machines:
|
|
73
|
-
|
|
74
77
|
```bash
|
|
75
|
-
claude-db use "mongodb+srv://user:pass@cluster.mongodb.net/memory"
|
|
76
78
|
claude-db use "postgres://user:pass@host:5432/memory"
|
|
79
|
+
claude-db use "mongodb+srv://user:pass@cluster.mongodb.net/memory"
|
|
77
80
|
```
|
|
78
81
|
|
|
79
|
-
Install the driver
|
|
80
|
-
default.
|
|
81
|
-
|
|
82
|
-
## With it, and without it
|
|
83
|
-
|
|
84
|
-
Asking _who defines and calls `closeObservations`_ by hand means a grep, then
|
|
85
|
-
opening three store adapters to see which hits are definitions. One `explain`
|
|
86
|
-
call answers it already classified: **2.1x cheaper**, measured across eight
|
|
87
|
-
real symbols in this repo.
|
|
88
|
-
|
|
89
|
-
Recall is the standing cost of ~180 tokens a prompt, skipped entirely on 28% of
|
|
90
|
-
prompts because the answer is already in context:
|
|
91
|
-
|
|
92
|
-
```
|
|
93
|
-
every prompt costs 180 tokens of recall
|
|
94
|
-
every lookup refunds 597 tokens (1,115 by hand - 518 with)
|
|
95
|
-
|
|
96
|
-
so one lookup pays for 3.3 prompts of recall
|
|
97
|
-
```
|
|
98
|
-
|
|
99
|
-
Check it on your own repo with `npm run bench:ab` and `npm run bench:tokens`
|
|
100
|
-
from a clone. [With and without](./docs/with-and-without.md) has every number,
|
|
101
|
-
including the symbols where plain grep wins.
|
|
102
|
-
|
|
103
|
-
## Commands
|
|
82
|
+
Install the driver first, with `npm install -g pg` or `npm install -g mongodb`.
|
|
83
|
+
Neither ships by default.
|
|
104
84
|
|
|
105
|
-
|
|
85
|
+
## Privacy
|
|
106
86
|
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
| `claude-db install [--project]` | Register hooks and the MCP server |
|
|
110
|
-
| `claude-db status` | Is it wired up, and when did it last record anything |
|
|
111
|
-
| `claude-db doctor [--deep]` | Resolved config; `--deep` proves a full round trip |
|
|
112
|
-
| `claude-db scan [--force]` | Build the code graph for this repo |
|
|
113
|
-
| `claude-db usages [--mode <m>] <symbol>` | What uses a symbol: live `git grep`, or the code graph |
|
|
114
|
-
| `claude-db use <url>` | Switch database and verify it |
|
|
115
|
-
| `claude-db view` | See this project's memory live in the browser |
|
|
87
|
+
Memory stays in your own database. Three things use the network, and each has
|
|
88
|
+
an off switch:
|
|
116
89
|
|
|
117
|
-
|
|
118
|
-
|
|
90
|
+
- **When a chat ends**, its saved, redacted text is sent once to Claude Haiku
|
|
91
|
+
through your own login, to make facts. Turn it off with `claude-db distill off`.
|
|
92
|
+
- **When a prompt has related memory**, the prompt, the end of Claude's last
|
|
93
|
+
reply and up to ten saved excerpts go to Haiku, so it can pick what to show.
|
|
94
|
+
Turn it off with `claude-db pick off`.
|
|
95
|
+
- **Once a day**, the npm registry is asked for the latest version. Turn it off
|
|
96
|
+
with `"updates": "off"` in the config.
|
|
119
97
|
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
98
|
+
`.env`, `secrets/`, `node_modules` and `.git/` are never stored. Text inside
|
|
99
|
+
`<private>...</private>` is stripped, and API keys and tokens are redacted
|
|
100
|
+
before anything is written or sent.
|
|
123
101
|
|
|
124
102
|
## Requirements
|
|
125
103
|
|
|
126
|
-
Node 22.
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
Embeddings run locally with a zero-dependency embedder. For real semantic
|
|
130
|
-
search, `npm install @xenova/transformers` and it upgrades itself.
|
|
131
|
-
|
|
132
|
-
## Privacy
|
|
133
|
-
|
|
134
|
-
Nothing leaves your machine unless you point it at a remote database.
|
|
135
|
-
`.env`, `secrets/`, `node_modules` and `.git/` are never stored, text wrapped
|
|
136
|
-
in `<private>...</private>` is stripped, and API keys and tokens are redacted
|
|
137
|
-
before anything is written.
|
|
104
|
+
Node 22.16 or newer. SQLite comes from Node's builtin `node:sqlite`, so nothing
|
|
105
|
+
compiles at install time. For real semantic search, run
|
|
106
|
+
`npm install -g @xenova/transformers` and the embedder upgrades itself.
|
|
138
107
|
|
|
139
108
|
## Documentation
|
|
140
109
|
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
[MCP tools](https://claude-db.vercel.app/docs/mcp-tools),
|
|
144
|
-
[how it works](https://claude-db.vercel.app/docs/how-it-works),
|
|
145
|
-
[databases](https://claude-db.vercel.app/docs/databases) and
|
|
146
|
-
[troubleshooting](https://claude-db.vercel.app/docs/troubleshooting)
|
|
110
|
+
- [Documentation site](https://claude-db.vercel.app/docs): the
|
|
111
|
+
[CLI reference](https://claude-db.vercel.app/docs/cli),
|
|
112
|
+
[MCP tools](https://claude-db.vercel.app/docs/mcp-tools),
|
|
113
|
+
[how it works](https://claude-db.vercel.app/docs/how-it-works),
|
|
114
|
+
[databases](https://claude-db.vercel.app/docs/databases) and
|
|
115
|
+
[troubleshooting](https://claude-db.vercel.app/docs/troubleshooting)
|
|
116
|
+
- [Setup guide](./docs/setup-guide.md): settings, habits and costs
|
|
117
|
+
- [With and without](./docs/with-and-without.md) and
|
|
118
|
+
[benchmarks](https://claude-db.vercel.app/docs/benchmarks): every number,
|
|
119
|
+
including the symbols where plain grep wins
|
|
120
|
+
- [Changelog](./CHANGELOG.md)
|
|
147
121
|
|
|
148
|
-
|
|
149
|
-
including the symbols where plain grep wins. Releases are in the
|
|
150
|
-
[changelog](./CHANGELOG.md).
|
|
151
|
-
|
|
152
|
-
## Development
|
|
122
|
+
## Contributing
|
|
153
123
|
|
|
154
124
|
```bash
|
|
155
125
|
npm install
|
|
156
126
|
npm run build
|
|
157
|
-
npm test
|
|
158
|
-
npm run lint
|
|
159
|
-
npm run try # simulate a session, touches nothing
|
|
160
|
-
npm run format
|
|
161
|
-
```
|
|
162
|
-
|
|
163
|
-
Releases publish from CI on a version tag:
|
|
164
|
-
|
|
165
|
-
```bash
|
|
166
|
-
npm version patch
|
|
167
|
-
git push --follow-tags
|
|
127
|
+
npm test
|
|
128
|
+
npm run lint
|
|
168
129
|
```
|
|
169
130
|
|
|
170
|
-
[CONTRIBUTING.md](./CONTRIBUTING.md) has the conventions, the test setup,
|
|
171
|
-
|
|
172
|
-
[SECURITY.md](./SECURITY.md), privately.
|
|
131
|
+
[CONTRIBUTING.md](./CONTRIBUTING.md) has the conventions, the test setup, how to
|
|
132
|
+
add a language to the code graph, and how releases are made. Security reports go
|
|
133
|
+
through [SECURITY.md](./SECURITY.md), privately.
|
|
173
134
|
|
|
174
135
|
## License
|
|
175
136
|
|
package/dist/capture/flush.d.ts
CHANGED
|
@@ -3,6 +3,7 @@ import type { Observation } from '../types.js';
|
|
|
3
3
|
export interface FlushResult {
|
|
4
4
|
observations: number;
|
|
5
5
|
summary: string | null;
|
|
6
|
+
lastReply: string;
|
|
6
7
|
}
|
|
7
8
|
export declare function flushSession(ctx: RecallContext, sessionId: string, project: string, transcriptPath?: string, rebuild?: boolean): Promise<FlushResult>;
|
|
8
9
|
export declare function embedObservations(ctx: RecallContext, observations: Observation[]): Promise<void>;
|
package/dist/capture/flush.js
CHANGED
|
@@ -8,16 +8,17 @@ export async function flushSession(ctx, sessionId, project, transcriptPath, rebu
|
|
|
8
8
|
const path = transcriptPath ?? transcriptPathFor(project, sessionId);
|
|
9
9
|
const cursor = readCursor(sessionId);
|
|
10
10
|
const { turns, nextOffset } = readTranscript(path, cursor);
|
|
11
|
+
const lastReply = turns.at(-1)?.reasoning ?? '';
|
|
11
12
|
if (turns.length === 0) {
|
|
12
13
|
await closeLandedWork(ctx.store, project);
|
|
13
14
|
writeCursor(sessionId, nextOffset);
|
|
14
|
-
return { observations: 0, summary: null };
|
|
15
|
+
return { observations: 0, summary: null, lastReply };
|
|
15
16
|
}
|
|
16
17
|
const observations = observationsFromTurns(turns, sessionId, project, ctx.config);
|
|
17
18
|
if (observations.length === 0) {
|
|
18
19
|
await closeLandedWork(ctx.store, project);
|
|
19
20
|
writeCursor(sessionId, nextOffset);
|
|
20
|
-
return { observations: 0, summary: null };
|
|
21
|
+
return { observations: 0, summary: null, lastReply };
|
|
21
22
|
}
|
|
22
23
|
await embedObservations(ctx, observations);
|
|
23
24
|
await ctx.store.insertObservations(observations);
|
|
@@ -31,7 +32,7 @@ export async function flushSession(ctx, sessionId, project, transcriptPath, rebu
|
|
|
31
32
|
summary,
|
|
32
33
|
});
|
|
33
34
|
writeCursor(sessionId, nextOffset);
|
|
34
|
-
return { observations: observations.length, summary };
|
|
35
|
+
return { observations: observations.length, summary, lastReply };
|
|
35
36
|
}
|
|
36
37
|
export async function embedObservations(ctx, observations) {
|
|
37
38
|
try {
|
package/dist/capture/git.js
CHANGED
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
import { execFileSync } from 'node:child_process';
|
|
2
2
|
import { join } from 'node:path';
|
|
3
3
|
import { observationId } from './identity.js';
|
|
4
|
-
import {
|
|
4
|
+
import { redact } from './redact.js';
|
|
5
|
+
import { classifyTurn, topLevelDirs } from './turn-extractor.js';
|
|
5
6
|
const RECORD = '';
|
|
6
7
|
const FIELD = '';
|
|
7
8
|
const NOT_WORTH_KEEPING = /^(v?\d+\.\d+\.\d+|merge |revert "|bump |release |chore\(release\)|\d+\.\d+\.\d+$)/i;
|
package/dist/capture/index.d.ts
CHANGED
|
@@ -5,8 +5,12 @@ export type { RememberInput } from './manual.js';
|
|
|
5
5
|
export { readTranscript, sessionIdsOnDisk, transcriptPathFor, transcriptsFor, } from './transcript.js';
|
|
6
6
|
export type { Turn, TranscriptRead } from './transcript.js';
|
|
7
7
|
export { observationsFromGit } from './git.js';
|
|
8
|
-
export { observationsFromTurns
|
|
8
|
+
export { observationsFromTurns } from './turn-extractor.js';
|
|
9
|
+
export { redact } from './redact.js';
|
|
10
|
+
export { claimScrub, finishScrub, releaseScrub, scrubSecrets } from './scrub.js';
|
|
9
11
|
export { flushSession, resetCursor, clearCursor, sweepCursors, summarize, embedObservations, } from './flush.js';
|
|
10
12
|
export type { FlushResult } from './flush.js';
|
|
11
13
|
export { closeLandedWork, openWork } from './progress.js';
|
|
14
|
+
export { REINGEST_VERSION, claimReingest, finishReingest, reingestDone, reingestProject, rememberedTranscripts, reingestSession, releaseReingest, } from './reingest.js';
|
|
15
|
+
export type { ProjectReingest, SessionReingest } from './reingest.js';
|
|
12
16
|
export { aiSummary, buildSummaryPrompt, validateSummary } from './summarize.js';
|
package/dist/capture/index.js
CHANGED
|
@@ -3,7 +3,10 @@ export { currentAuthor, observationId } from './identity.js';
|
|
|
3
3
|
export { remember } from './manual.js';
|
|
4
4
|
export { readTranscript, sessionIdsOnDisk, transcriptPathFor, transcriptsFor, } from './transcript.js';
|
|
5
5
|
export { observationsFromGit } from './git.js';
|
|
6
|
-
export { observationsFromTurns
|
|
6
|
+
export { observationsFromTurns } from './turn-extractor.js';
|
|
7
|
+
export { redact } from './redact.js';
|
|
8
|
+
export { claimScrub, finishScrub, releaseScrub, scrubSecrets } from './scrub.js';
|
|
7
9
|
export { flushSession, resetCursor, clearCursor, sweepCursors, summarize, embedObservations, } from './flush.js';
|
|
8
10
|
export { closeLandedWork, openWork } from './progress.js';
|
|
11
|
+
export { REINGEST_VERSION, claimReingest, finishReingest, reingestDone, reingestProject, rememberedTranscripts, reingestSession, releaseReingest, } from './reingest.js';
|
|
9
12
|
export { aiSummary, buildSummaryPrompt, validateSummary } from './summarize.js';
|
package/dist/capture/manual.js
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { embedObservations } from './flush.js';
|
|
2
2
|
import { currentAuthor, observationId } from './identity.js';
|
|
3
|
-
import { redact } from './
|
|
3
|
+
import { redact } from './redact.js';
|
|
4
4
|
export async function remember(ctx, input) {
|
|
5
5
|
const createdAt = Date.now();
|
|
6
6
|
const author = currentAuthor();
|
package/dist/capture/progress.js
CHANGED
|
@@ -7,6 +7,7 @@ function uncommittedFiles(project) {
|
|
|
7
7
|
const raw = execFileSync('git', ['-C', project, 'status', '--porcelain', '-z'], {
|
|
8
8
|
encoding: 'utf8',
|
|
9
9
|
maxBuffer: MAX_BUFFER,
|
|
10
|
+
stdio: ['ignore', 'pipe', 'ignore'],
|
|
10
11
|
});
|
|
11
12
|
const files = new Set();
|
|
12
13
|
const fields = raw.split('\0');
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export declare function redact(text: string): string;
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
const PRIVATE_BLOCK = /<private>[\s\S]*?(?:<\/private>|$)/gi;
|
|
2
|
+
const PRIVATE_KEY = /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g;
|
|
3
|
+
const SECRET_NAME = '[A-Za-z0-9_]*(?:token|secret|password|passwd|api[_-]?key|access[_-]?key)[A-Za-z0-9_]*';
|
|
4
|
+
const UNQUOTED_SECRET = new RegExp(`\\b(${SECRET_NAME})(\\s*[:=]\\s*)(?=[^\\s"'\`,;]*[A-Za-z])[^\\s"'\`,;\\[]{8,}`, 'gi');
|
|
5
|
+
export function redact(text) {
|
|
6
|
+
return text
|
|
7
|
+
.replace(PRIVATE_BLOCK, '[redacted]')
|
|
8
|
+
.replace(PRIVATE_KEY, '[redacted-private-key]')
|
|
9
|
+
.replace(/\/\/[^\s:/@]+:[^\s@]+@/g, '//[redacted]@')
|
|
10
|
+
.replace(/\b(sk-[A-Za-z0-9_-]{16,})\b/g, '[redacted-key]')
|
|
11
|
+
.replace(/\b(gh[pousr]_[A-Za-z0-9]{16,})\b/g, '[redacted-token]')
|
|
12
|
+
.replace(/\bAKIA[0-9A-Z]{16}\b/g, '[redacted-key]')
|
|
13
|
+
.replace(/\bxox[baprs]-[A-Za-z0-9-]{10,}/g, '[redacted-token]')
|
|
14
|
+
.replace(/\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/g, '[redacted-jwt]')
|
|
15
|
+
.replace(/(?<=(password|secret|token|api[_-]?key)"?\s*[:=]\s*)"[^"]+"/gi, '"[redacted]"')
|
|
16
|
+
.replace(UNQUOTED_SECRET, '$1$2[redacted]');
|
|
17
|
+
}
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
import type { RecallContext } from '../context.js';
|
|
2
|
+
export declare const REINGEST_VERSION = 1;
|
|
3
|
+
export interface SessionReingest {
|
|
4
|
+
sessionId: string;
|
|
5
|
+
saved: number;
|
|
6
|
+
replaced: number;
|
|
7
|
+
}
|
|
8
|
+
export interface ProjectReingest {
|
|
9
|
+
transcripts: number;
|
|
10
|
+
saved: number;
|
|
11
|
+
replaced: number;
|
|
12
|
+
}
|
|
13
|
+
export declare function reingestSession(ctx: RecallContext, project: string, path: string): Promise<SessionReingest>;
|
|
14
|
+
export declare function rememberedTranscripts(ctx: RecallContext, project: string, paths?: string[]): Promise<string[]>;
|
|
15
|
+
export declare function reingestProject(ctx: RecallContext, project: string, paths?: string[], onSession?: (result: SessionReingest) => void): Promise<ProjectReingest>;
|
|
16
|
+
export declare function reingestDone(project: string): boolean;
|
|
17
|
+
export declare function claimReingest(project: string, now?: number): boolean;
|
|
18
|
+
export declare function finishReingest(project: string): void;
|
|
19
|
+
export declare function releaseReingest(project: string): void;
|