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.
Files changed (161) hide show
  1. package/CHANGELOG.md +252 -0
  2. package/README.md +74 -113
  3. package/dist/capture/flush.d.ts +1 -0
  4. package/dist/capture/flush.js +4 -3
  5. package/dist/capture/git.js +2 -1
  6. package/dist/capture/index.d.ts +5 -1
  7. package/dist/capture/index.js +4 -1
  8. package/dist/capture/manual.js +1 -1
  9. package/dist/capture/progress.js +1 -0
  10. package/dist/capture/redact.d.ts +1 -0
  11. package/dist/capture/redact.js +17 -0
  12. package/dist/capture/reingest.d.ts +19 -0
  13. package/dist/capture/reingest.js +56 -0
  14. package/dist/capture/scrub.d.ts +11 -0
  15. package/dist/capture/scrub.js +48 -0
  16. package/dist/capture/summarize.js +3 -9
  17. package/dist/capture/transcript.d.ts +1 -0
  18. package/dist/capture/transcript.js +12 -3
  19. package/dist/capture/turn-extractor.d.ts +0 -1
  20. package/dist/capture/turn-extractor.js +10 -19
  21. package/dist/cli/commands/adoption.js +3 -3
  22. package/dist/cli/commands/distill.d.ts +1 -0
  23. package/dist/cli/commands/distill.js +67 -0
  24. package/dist/cli/commands/doctor.js +13 -5
  25. package/dist/cli/commands/insight.js +14 -4
  26. package/dist/cli/commands/maintain.d.ts +2 -1
  27. package/dist/cli/commands/maintain.js +54 -18
  28. package/dist/cli/commands/pick.d.ts +3 -0
  29. package/dist/cli/commands/pick.js +25 -0
  30. package/dist/cli/commands/setup.js +14 -5
  31. package/dist/cli/commands/sync.js +73 -12
  32. package/dist/cli/commands/transfer.d.ts +0 -5
  33. package/dist/cli/commands/transfer.js +1 -24
  34. package/dist/cli/commands/use.js +1 -1
  35. package/dist/cli/commands/view.js +31 -28
  36. package/dist/cli/index.js +13 -2
  37. package/dist/cli/install.d.ts +2 -0
  38. package/dist/cli/install.js +44 -21
  39. package/dist/cli/instructions.js +4 -2
  40. package/dist/cli/refresh.js +5 -1
  41. package/dist/cli/usage.js +4 -0
  42. package/dist/config/dir.d.ts +1 -0
  43. package/dist/config/dir.js +3 -0
  44. package/dist/config/index.d.ts +1 -1
  45. package/dist/config/index.js +1 -1
  46. package/dist/config/load.d.ts +4 -1
  47. package/dist/config/load.js +30 -13
  48. package/dist/config/schema.d.ts +19 -0
  49. package/dist/config/schema.js +17 -2
  50. package/dist/embed/index.d.ts +1 -1
  51. package/dist/embed/index.js +1 -1
  52. package/dist/embed/local.js +2 -1
  53. package/dist/facts/budget.d.ts +4 -0
  54. package/dist/facts/budget.js +12 -0
  55. package/dist/facts/claude-memory.d.ts +19 -0
  56. package/dist/facts/claude-memory.js +100 -0
  57. package/dist/facts/distill.d.ts +25 -0
  58. package/dist/facts/distill.js +141 -0
  59. package/dist/facts/model.d.ts +28 -0
  60. package/dist/facts/model.js +82 -0
  61. package/dist/facts/notice.d.ts +2 -0
  62. package/dist/facts/notice.js +22 -0
  63. package/dist/facts/ops.d.ts +23 -0
  64. package/dist/facts/ops.js +91 -0
  65. package/dist/facts/render.d.ts +4 -0
  66. package/dist/facts/render.js +13 -0
  67. package/dist/facts/start.d.ts +6 -0
  68. package/dist/facts/start.js +57 -0
  69. package/dist/graph/index.d.ts +2 -6
  70. package/dist/graph/index.js +2 -3
  71. package/dist/graph/languages/basic.js +1 -1
  72. package/dist/graph/languages/index.d.ts +1 -1
  73. package/dist/graph/parser.js +1 -1
  74. package/dist/graph/query/index.d.ts +0 -2
  75. package/dist/graph/query/index.js +0 -1
  76. package/dist/graph/scan/extract.js +1 -1
  77. package/dist/graph/scan/files.js +1 -1
  78. package/dist/graph/scan/index.d.ts +1 -2
  79. package/dist/graph/scan/index.js +1 -1
  80. package/dist/hooks/background.d.ts +3 -0
  81. package/dist/hooks/background.js +43 -0
  82. package/dist/hooks/compact.d.ts +8 -0
  83. package/dist/hooks/compact.js +42 -0
  84. package/dist/hooks/payload.d.ts +3 -0
  85. package/dist/hooks/payload.js +18 -1
  86. package/dist/hooks/pick-deliver.d.ts +2 -0
  87. package/dist/hooks/pick-deliver.js +16 -0
  88. package/dist/hooks/prompt-recall.d.ts +21 -0
  89. package/dist/hooks/prompt-recall.js +36 -0
  90. package/dist/hooks/relevance.d.ts +11 -3
  91. package/dist/hooks/relevance.js +56 -26
  92. package/dist/hooks/session-end.js +7 -1
  93. package/dist/hooks/session-start.js +31 -59
  94. package/dist/hooks/shown.d.ts +1 -0
  95. package/dist/hooks/shown.js +5 -2
  96. package/dist/hooks/start-legacy.d.ts +6 -0
  97. package/dist/hooks/start-legacy.js +47 -0
  98. package/dist/hooks/user-prompt.js +29 -25
  99. package/dist/mcp/server.js +13 -1
  100. package/dist/pick/pending.d.ts +17 -0
  101. package/dist/pick/pending.js +106 -0
  102. package/dist/pick/prompt.d.ts +14 -0
  103. package/dist/pick/prompt.js +80 -0
  104. package/dist/pick/run.d.ts +22 -0
  105. package/dist/pick/run.js +36 -0
  106. package/dist/pick/worker.d.ts +2 -0
  107. package/dist/pick/worker.js +32 -0
  108. package/dist/store/adapter.d.ts +1 -0
  109. package/dist/store/each.d.ts +5 -0
  110. package/dist/store/each.js +25 -0
  111. package/dist/store/mongo/docs.d.ts +2 -0
  112. package/dist/store/mongo/docs.js +4 -0
  113. package/dist/store/mongo/driver.js +3 -2
  114. package/dist/store/mongo/filters.d.ts +1 -0
  115. package/dist/store/mongo/filters.js +8 -0
  116. package/dist/store/mongo/index.d.ts +1 -0
  117. package/dist/store/mongo/index.js +5 -2
  118. package/dist/store/mongo/observations.d.ts +2 -1
  119. package/dist/store/mongo/observations.js +11 -1
  120. package/dist/store/mongo/search.js +12 -3
  121. package/dist/store/mongo/sessions.js +7 -1
  122. package/dist/store/mongo/vectorSearch.js +9 -11
  123. package/dist/store/postgres/driver.js +3 -2
  124. package/dist/store/postgres/filters.js +5 -0
  125. package/dist/store/postgres/index.d.ts +1 -0
  126. package/dist/store/postgres/index.js +3 -0
  127. package/dist/store/postgres/meta.js +2 -1
  128. package/dist/store/postgres/observations.d.ts +1 -0
  129. package/dist/store/postgres/observations.js +14 -3
  130. package/dist/store/postgres/rows.js +4 -0
  131. package/dist/store/postgres/schema.d.ts +2 -2
  132. package/dist/store/postgres/schema.js +4 -1
  133. package/dist/store/postgres/sessions.js +14 -7
  134. package/dist/store/session-time.d.ts +2 -0
  135. package/dist/store/session-time.js +5 -0
  136. package/dist/store/sqlite/filters.js +5 -0
  137. package/dist/store/sqlite/index.d.ts +1 -0
  138. package/dist/store/sqlite/index.js +23 -4
  139. package/dist/store/sqlite/observations.d.ts +1 -0
  140. package/dist/store/sqlite/observations.js +14 -1
  141. package/dist/store/sqlite/rows.js +4 -0
  142. package/dist/store/sqlite/schema.sql +3 -1
  143. package/dist/store/sqlite/search.js +7 -3
  144. package/dist/store/sqlite/sessions.js +13 -8
  145. package/dist/types.d.ts +5 -1
  146. package/dist/usages/find.js +5 -3
  147. package/dist/usages/index.d.ts +0 -1
  148. package/dist/util/claude-cli.d.ts +6 -0
  149. package/dist/util/claude-cli.js +38 -0
  150. package/dist/util/daily-budget.d.ts +7 -0
  151. package/dist/util/daily-budget.js +38 -0
  152. package/dist/util/day.d.ts +1 -0
  153. package/dist/util/day.js +11 -0
  154. package/dist/util/job-lock.d.ts +4 -0
  155. package/dist/util/job-lock.js +56 -0
  156. package/dist/util/prompt.d.ts +5 -0
  157. package/dist/util/prompt.js +31 -0
  158. package/docs/how-it-works.md +69 -3
  159. package/docs/setup-guide.md +339 -0
  160. package/docs/with-and-without.md +43 -36
  161. package/package.json +23 -7
@@ -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. Tokens are approximated at 4 characters each.
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 about three prompts of recall.**
13
+ **One lookup pays for over thirty prompts of recall.**
12
14
 
13
- Recall costs ~180 tokens on every prompt. A symbol lookup saves ~600 tokens
14
- against doing the same work by hand. Ask your codebase something once every few
15
- prompts and you are ahead. Never ask it anything and you are paying for context
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 1734 1228 1153 2381
31
- observationsFromTurns 2042 2362 7529 9891
32
- closeObservations 3209 1354 6597 7951
33
- flushSession 1786 818 4442 5260
34
- refreshGraph 2640 1143 961 2104
35
- observationId 2020 2418 572 2990
36
- toSnippet 1994 1789 704 2493
37
- openWork 1166 1294 1305 2599
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 16591 35669
40
- TOTAL tokens 4148 8917
41
- 2.1x
41
+ TOTAL chars 20899 42828
42
+ TOTAL tokens 5225 10707
43
+ 2.0x
42
44
  ```
43
45
 
44
- **518 tokens per lookup instead of 1,115.**
46
+ **653 tokens per lookup instead of 1,338.**
45
47
 
46
- The average hides something useful. `refreshGraph` and `observationId` are
47
- cheaper _without_ claude-db, because their defining files are small and grep
48
- answers them fine. `observationsFromTurns` and `closeObservations` are four to
49
- five times cheaper with it, because answering those by hand means reading a
50
- 200-line file, or three of them spread across different modules.
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 on every prompt, so it has a standing cost. What
69
- arrives is index lines, never full bodies: an id, a kind, a date, a title, and
70
- the line that matched. Claude pulls a full body only when a title earns it.
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 180 tokens of recall
74
- every lookup refunds 597 tokens (1,115 by hand, 518 with)
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 3.3 prompts of recall
81
+ so one lookup pays for 33.9 prompts of recall
77
82
  ```
78
83
 
79
- On 28% of prompts nothing is injected at all, because everything matching is
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 180 0.3
86
- 5 prompts 900 1.5
87
- 10 prompts 1,800 3.0
88
- 20 prompts 3,600 6.0
89
- 60 prompts 10,800 18.1
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.9.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.5"
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
- "postinstall": "node -e \"const v=process.versions.node.split('.').map(Number); if(v[0]<22||(v[0]===22&&v[1]<5)){console.error('\\n claude-db needs Node >= 22.5 (node:sqlite is builtin from there). You have '+process.versions.node+'.\\n');process.exit(1)}\"",
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
- "typescript": "^5.9.3"
74
+ "publint": "^0.3.25",
75
+ "typescript": "^5.9.3",
76
+ "typescript-eslint": "^8.71.1"
61
77
  },
62
78
  "keywords": [
63
79
  "claude",