claude-db 0.9.0 → 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 +252 -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 +13 -5
- package/dist/cli/commands/insight.js +14 -4
- package/dist/cli/commands/maintain.d.ts +2 -1
- package/dist/cli/commands/maintain.js +54 -18
- package/dist/cli/commands/pick.d.ts +3 -0
- package/dist/cli/commands/pick.js +25 -0
- package/dist/cli/commands/setup.js +14 -5
- 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 +31 -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/docs/with-and-without.md
CHANGED
|
@@ -4,16 +4,18 @@ Does it actually save tokens? Here is the same work measured both ways, so you
|
|
|
4
4
|
can decide before you install.
|
|
5
5
|
|
|
6
6
|
Run `npm run bench:ab` from a clone to reproduce all of it on your own
|
|
7
|
-
codebase.
|
|
7
|
+
codebase. Recall is priced by replaying real chats through the prompt hook, so
|
|
8
|
+
pass `--recall-from <project>` to pick a project that has memory. Tokens are
|
|
9
|
+
approximated at 4 characters each.
|
|
8
10
|
|
|
9
11
|
## The short answer
|
|
10
12
|
|
|
11
|
-
**One lookup pays for
|
|
13
|
+
**One lookup pays for over thirty prompts of recall.**
|
|
12
14
|
|
|
13
|
-
Recall costs ~
|
|
14
|
-
against doing the same work by hand. Ask
|
|
15
|
-
|
|
16
|
-
you did not use.
|
|
15
|
+
Recall costs ~20 tokens a prompt on average, and nothing at all on about two
|
|
16
|
+
thirds of them. A symbol lookup saves ~700 tokens against doing the same work by hand. Ask
|
|
17
|
+
your codebase something once every thirty prompts and you are ahead. Never ask
|
|
18
|
+
it anything and you are paying for context you did not use.
|
|
17
19
|
|
|
18
20
|
## Looking up a symbol
|
|
19
21
|
|
|
@@ -27,27 +29,28 @@ Measured on eight real symbols in this repository:
|
|
|
27
29
|
```
|
|
28
30
|
symbol WITH grep +read WITHOUT
|
|
29
31
|
---------------------------------------------------------
|
|
30
|
-
isSearchable
|
|
31
|
-
observationsFromTurns
|
|
32
|
-
closeObservations
|
|
33
|
-
flushSession
|
|
34
|
-
refreshGraph
|
|
35
|
-
observationId
|
|
36
|
-
toSnippet
|
|
37
|
-
openWork
|
|
32
|
+
isSearchable 1935 1273 2455 3728
|
|
33
|
+
observationsFromTurns 3428 3664 7489 11153
|
|
34
|
+
closeObservations 4340 2487 6943 9430
|
|
35
|
+
flushSession 2431 924 4830 5754
|
|
36
|
+
refreshGraph 2796 1096 961 2057
|
|
37
|
+
observationId 2519 4014 572 4586
|
|
38
|
+
toSnippet 2006 1789 704 2493
|
|
39
|
+
openWork 1444 1492 2135 3627
|
|
38
40
|
---------------------------------------------------------
|
|
39
|
-
TOTAL chars
|
|
40
|
-
TOTAL tokens
|
|
41
|
-
2.
|
|
41
|
+
TOTAL chars 20899 42828
|
|
42
|
+
TOTAL tokens 5225 10707
|
|
43
|
+
2.0x
|
|
42
44
|
```
|
|
43
45
|
|
|
44
|
-
**
|
|
46
|
+
**653 tokens per lookup instead of 1,338.**
|
|
45
47
|
|
|
46
|
-
The average hides something useful. `refreshGraph`
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
48
|
+
The average hides something useful. `refreshGraph` is cheaper _without_
|
|
49
|
+
claude-db, because its defining file is small and grep answers it fine.
|
|
50
|
+
`observationsFromTurns` is more than three times cheaper with it, because
|
|
51
|
+
answering it by hand means reading a 250-line file, and `closeObservations`
|
|
52
|
+
about twice as cheap, because its definitions are spread across three store
|
|
53
|
+
adapters.
|
|
51
54
|
|
|
52
55
|
The win concentrates on questions that span files, which is also where a wrong
|
|
53
56
|
answer costs you the most.
|
|
@@ -65,28 +68,32 @@ explaining it to Claude again yourself, which no benchmark can price.
|
|
|
65
68
|
|
|
66
69
|
## What it costs
|
|
67
70
|
|
|
68
|
-
Recall arrives automatically
|
|
69
|
-
|
|
70
|
-
|
|
71
|
+
Recall arrives automatically whenever Haiku finds an earlier memory that fits
|
|
72
|
+
the prompt, so it has a standing cost. What arrives is one line per memory,
|
|
73
|
+
never a full body: the day, the question that memory answered, one sentence
|
|
74
|
+
copied from it, and the id to expand. Claude pulls a full body only when a line
|
|
75
|
+
earns it.
|
|
71
76
|
|
|
72
77
|
```
|
|
73
|
-
every prompt costs
|
|
74
|
-
every lookup refunds
|
|
78
|
+
every prompt costs 20 tokens of recall
|
|
79
|
+
every lookup refunds 685 tokens (1,338 by hand, 653 with)
|
|
75
80
|
|
|
76
|
-
so one lookup pays for
|
|
81
|
+
so one lookup pays for 33.9 prompts of recall
|
|
77
82
|
```
|
|
78
83
|
|
|
79
|
-
On
|
|
80
|
-
already in the conversation.
|
|
84
|
+
On 69% of prompts nothing is injected at all: nothing from an earlier chat
|
|
85
|
+
fits well enough, or what fits is already in the conversation. Recall was
|
|
86
|
+
priced by replaying 300 real prompts, in order, from a project with about 660
|
|
87
|
+
memories.
|
|
81
88
|
|
|
82
89
|
```
|
|
83
90
|
a session of recall costs lookups to break even
|
|
84
91
|
------------------------------------------------------
|
|
85
|
-
1 prompt
|
|
86
|
-
5 prompts
|
|
87
|
-
10 prompts
|
|
88
|
-
20 prompts
|
|
89
|
-
60 prompts
|
|
92
|
+
1 prompt 20 0.0
|
|
93
|
+
5 prompts 101 0.1
|
|
94
|
+
10 prompts 202 0.3
|
|
95
|
+
20 prompts 405 0.6
|
|
96
|
+
60 prompts 1,214 1.8
|
|
90
97
|
```
|
|
91
98
|
|
|
92
99
|
## When it does not pay off
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "claude-db",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.10.0",
|
|
4
4
|
"description": "Persistent memory for Claude Code. Captures why decisions were made, not just which files changed. Bring your own database: SQLite, MongoDB or Postgres. No cloud, no subscription.",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"type": "module",
|
|
@@ -17,20 +17,26 @@
|
|
|
17
17
|
"files": [
|
|
18
18
|
"dist",
|
|
19
19
|
"skills",
|
|
20
|
-
"docs",
|
|
20
|
+
"docs/how-it-works.md",
|
|
21
|
+
"docs/with-and-without.md",
|
|
22
|
+
"docs/setup-guide.md",
|
|
21
23
|
"README.md",
|
|
22
24
|
"CHANGELOG.md",
|
|
23
25
|
"LICENSE"
|
|
24
26
|
],
|
|
25
27
|
"engines": {
|
|
26
|
-
"node": ">=22.
|
|
28
|
+
"node": ">=22.16"
|
|
27
29
|
},
|
|
28
30
|
"scripts": {
|
|
29
|
-
"build": "tsc -p tsconfig.json && node scripts/copy-assets.mjs",
|
|
31
|
+
"build": "tsc -p tsconfig.json && node scripts/copy-assets.mjs && node scripts/prune-dist.mjs",
|
|
30
32
|
"dev": "tsc -w -p tsconfig.json",
|
|
31
33
|
"typecheck": "tsc --noEmit -p tsconfig.json",
|
|
32
|
-
"lint": "node scripts/lint.mjs",
|
|
34
|
+
"lint": "node scripts/lint.mjs && eslint . && node scripts/check-fixtures.mjs",
|
|
35
|
+
"check:fixtures": "node scripts/check-fixtures.mjs",
|
|
33
36
|
"test": "node scripts/unit.mjs && node scripts/local.mjs && node scripts/filter.mjs && node scripts/transcript.mjs && node scripts/inject.mjs && node scripts/smoke.mjs",
|
|
37
|
+
"coverage": "c8 npm test",
|
|
38
|
+
"check:package": "npm run build && publint && attw --pack . --profile esm-only",
|
|
39
|
+
"knip": "knip",
|
|
34
40
|
"smoke": "node scripts/smoke.mjs",
|
|
35
41
|
"unit": "node scripts/unit.mjs",
|
|
36
42
|
"local": "node scripts/local.mjs",
|
|
@@ -38,7 +44,8 @@
|
|
|
38
44
|
"bench": "node scripts/bench.mjs",
|
|
39
45
|
"bench:tokens": "node scripts/bench-tokens.mjs",
|
|
40
46
|
"bench:ab": "node scripts/bench-ab.mjs",
|
|
41
|
-
"
|
|
47
|
+
"bench:inject": "node scripts/bench-inject.mjs",
|
|
48
|
+
"postinstall": "node -e \"const v=process.versions.node.split('.').map(Number); if(v[0]<22||(v[0]===22&&v[1]<16)){console.error('\\n claude-db needs Node >= 22.16 (its builtin SQLite has full-text search from there). You have '+process.versions.node+'.\\n');process.exit(1)}\"",
|
|
42
49
|
"prepublishOnly": "npm run build && npm test",
|
|
43
50
|
"format": "prettier --write .",
|
|
44
51
|
"format:check": "prettier --check ."
|
|
@@ -55,9 +62,18 @@
|
|
|
55
62
|
"zod": "^4.4.3"
|
|
56
63
|
},
|
|
57
64
|
"devDependencies": {
|
|
65
|
+
"@arethetypeswrong/cli": "^0.18.5",
|
|
66
|
+
"@eslint/js": "^10.0.1",
|
|
58
67
|
"@types/node": "^22.20.1",
|
|
68
|
+
"c8": "^12.0.0",
|
|
69
|
+
"eslint": "^10.12.0",
|
|
70
|
+
"eslint-config-prettier": "^10.1.8",
|
|
71
|
+
"globals": "^17.13.0",
|
|
72
|
+
"knip": "^6.39.0",
|
|
59
73
|
"prettier": "^3.8.0",
|
|
60
|
-
"
|
|
74
|
+
"publint": "^0.3.25",
|
|
75
|
+
"typescript": "^5.9.3",
|
|
76
|
+
"typescript-eslint": "^8.71.1"
|
|
61
77
|
},
|
|
62
78
|
"keywords": [
|
|
63
79
|
"claude",
|