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
@@ -0,0 +1,38 @@
1
+ import { execFile } from 'node:child_process';
2
+ const MAX_BUFFER = 1024 * 1024;
3
+ const OPTIONAL_FLAGS = [
4
+ ['--effort', 'low'],
5
+ ['--no-session-persistence'],
6
+ ];
7
+ const UNKNOWN_OPTION = /unknown option '(--[\w-]+)'/i;
8
+ export function claudeBinary(env = process.env) {
9
+ return env['CLAUDE_CODE_EXECPATH'] || 'claude';
10
+ }
11
+ export async function runHeadless(prompt, model, timeoutMs, options = {}) {
12
+ let optional = [...OPTIONAL_FLAGS, ...(options.flags ?? [])];
13
+ for (;;) {
14
+ const result = await call(['-p', prompt, '--model', model, ...optional.flat()], timeoutMs, options.env ?? {});
15
+ if (result.stdout !== null)
16
+ return result.stdout;
17
+ const rejected = UNKNOWN_OPTION.exec(result.stderr)?.[1];
18
+ const remaining = optional.filter((flags) => flags[0] !== rejected);
19
+ if (remaining.length === optional.length)
20
+ return null;
21
+ optional = remaining;
22
+ }
23
+ }
24
+ function call(args, timeoutMs, env) {
25
+ return new Promise((done) => {
26
+ try {
27
+ const child = execFile(claudeBinary(), args, {
28
+ timeout: timeoutMs,
29
+ maxBuffer: MAX_BUFFER,
30
+ env: { ...process.env, ...env, CLAUDE_DB_CAPTURE: 'off' },
31
+ }, (error, stdout, stderr) => done({ stdout: error ? null : stdout, stderr: String(stderr) }));
32
+ child.stdin?.end();
33
+ }
34
+ catch {
35
+ done({ stdout: null, stderr: '' });
36
+ }
37
+ });
38
+ }
@@ -0,0 +1,7 @@
1
+ export interface BudgetUsage {
2
+ used: number;
3
+ pausedUntil: number;
4
+ }
5
+ export declare function budgetUsage(name: string, now?: number): BudgetUsage;
6
+ export declare function takeBudget(name: string, limit: number, count: number, now?: number): boolean;
7
+ export declare function pauseBudget(name: string, ms: number, now?: number): void;
@@ -0,0 +1,38 @@
1
+ import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
2
+ import { join } from 'node:path';
3
+ import { CONFIG_DIR } from '../config/dir.js';
4
+ function budgetPath(name) {
5
+ return join(CONFIG_DIR, name, 'budget.json');
6
+ }
7
+ function today(now) {
8
+ return new Date(now).toISOString().slice(0, 10);
9
+ }
10
+ function read(name, now) {
11
+ let saved = {};
12
+ try {
13
+ saved = JSON.parse(readFileSync(budgetPath(name), 'utf8'));
14
+ }
15
+ catch { }
16
+ const pausedUntil = Number(saved.pausedUntil) || 0;
17
+ if (saved.day !== today(now))
18
+ return { day: today(now), used: 0, pausedUntil };
19
+ return { day: saved.day, used: Number(saved.used) || 0, pausedUntil };
20
+ }
21
+ function write(name, budget) {
22
+ mkdirSync(join(CONFIG_DIR, name), { recursive: true });
23
+ writeFileSync(budgetPath(name), `${JSON.stringify(budget)}\n`, 'utf8');
24
+ }
25
+ export function budgetUsage(name, now = Date.now()) {
26
+ const budget = read(name, now);
27
+ return { used: budget.used, pausedUntil: budget.pausedUntil };
28
+ }
29
+ export function takeBudget(name, limit, count, now = Date.now()) {
30
+ const budget = read(name, now);
31
+ if (budget.pausedUntil > now || budget.used + count > limit)
32
+ return false;
33
+ write(name, { ...budget, used: budget.used + count });
34
+ return true;
35
+ }
36
+ export function pauseBudget(name, ms, now = Date.now()) {
37
+ write(name, { ...read(name, now), pausedUntil: now + ms });
38
+ }
@@ -0,0 +1 @@
1
+ export declare function formatDay(at: number, now?: number): string;
@@ -0,0 +1,11 @@
1
+ const THIS_YEAR = new Intl.DateTimeFormat('en-US', { month: 'short', day: 'numeric' });
2
+ const OTHER_YEAR = new Intl.DateTimeFormat('en-US', {
3
+ month: 'short',
4
+ day: 'numeric',
5
+ year: 'numeric',
6
+ });
7
+ export function formatDay(at, now = Date.now()) {
8
+ const date = new Date(at);
9
+ const format = date.getFullYear() === new Date(now).getFullYear() ? THIS_YEAR : OTHER_YEAR;
10
+ return format.format(date);
11
+ }
@@ -0,0 +1,4 @@
1
+ export declare function jobMark(job: string, key: string): number;
2
+ export declare function claimJob(job: string, key: string, now?: number): boolean;
3
+ export declare function finishJob(job: string, key: string, mark: number): void;
4
+ export declare function releaseJob(job: string, key: string): void;
@@ -0,0 +1,56 @@
1
+ import { mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
2
+ import { join } from 'node:path';
3
+ import { CONFIG_DIR } from '../config/index.js';
4
+ import { scopeToken } from './scope.js';
5
+ const STALE_LOCK_MS = 10 * 60_000;
6
+ function jobDir(job) {
7
+ return join(CONFIG_DIR, job);
8
+ }
9
+ function lockPath(job, key) {
10
+ return join(jobDir(job), `${scopeToken(key)}.lock`);
11
+ }
12
+ function markPath(job, key) {
13
+ return join(jobDir(job), `${scopeToken(key)}.done`);
14
+ }
15
+ export function jobMark(job, key) {
16
+ try {
17
+ return Number(readFileSync(markPath(job, key), 'utf8')) || 0;
18
+ }
19
+ catch {
20
+ return 0;
21
+ }
22
+ }
23
+ export function claimJob(job, key, now = Date.now()) {
24
+ const lock = lockPath(job, key);
25
+ mkdirSync(jobDir(job), { recursive: true });
26
+ if (tryLock(lock, now))
27
+ return true;
28
+ let lockedAt;
29
+ try {
30
+ lockedAt = statSync(lock).mtimeMs;
31
+ }
32
+ catch {
33
+ return tryLock(lock, now);
34
+ }
35
+ if (now - lockedAt < STALE_LOCK_MS)
36
+ return false;
37
+ rmSync(lock, { force: true });
38
+ return tryLock(lock, now);
39
+ }
40
+ export function finishJob(job, key, mark) {
41
+ mkdirSync(jobDir(job), { recursive: true });
42
+ writeFileSync(markPath(job, key), String(mark), 'utf8');
43
+ rmSync(lockPath(job, key), { force: true });
44
+ }
45
+ export function releaseJob(job, key) {
46
+ rmSync(lockPath(job, key), { force: true });
47
+ }
48
+ function tryLock(lock, now) {
49
+ try {
50
+ writeFileSync(lock, String(now), { flag: 'wx' });
51
+ return true;
52
+ }
53
+ catch {
54
+ return false;
55
+ }
56
+ }
@@ -1 +1,6 @@
1
+ export declare function isRelayedMessage(text: string): boolean;
2
+ export declare function withoutImageMarkers(text: string): string;
3
+ export declare function withoutIdeContext(text: string): string;
4
+ export declare function typedPrompt(prompt: string): string | null;
5
+ export declare function readablePrompt(prompt: string): string;
1
6
  export declare function isSearchable(prompt: string): boolean;
@@ -57,6 +57,37 @@ const NOISE = new Set([
57
57
  'should',
58
58
  ]);
59
59
  const DENSE_SCRIPT = /[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Hangul}]/gu;
60
+ const RELAYED_MESSAGE = /^(?:[^<\n]*\n)?<(?:agent-message|task-notification)\b/;
61
+ const COMMAND_MESSAGE = /^<(?:command-name|command-message|local-command-[a-z]+)\b/;
62
+ const COMMAND_NAME = /<command-name>([^<]*)<\/command-name>/;
63
+ const COMMAND_ARGS = /<command-args>([^<]*)<\/command-args>/;
64
+ const IMAGE_MARKER = /\[Image: (?:source: |original )[^\]\n]*\]/g;
65
+ const IDE_CONTEXT = /<(ide_[a-z_]+)>[\s\S]*?<\/\1>/g;
66
+ export function isRelayedMessage(text) {
67
+ return RELAYED_MESSAGE.test(text.trim());
68
+ }
69
+ export function withoutImageMarkers(text) {
70
+ return text
71
+ .replace(IMAGE_MARKER, ' ')
72
+ .replace(/[ \t]{2,}/g, ' ')
73
+ .trim();
74
+ }
75
+ export function withoutIdeContext(text) {
76
+ return text.replace(IDE_CONTEXT, ' ');
77
+ }
78
+ export function typedPrompt(prompt) {
79
+ const text = prompt.trim();
80
+ if (RELAYED_MESSAGE.test(text) || COMMAND_MESSAGE.test(text))
81
+ return null;
82
+ return withoutImageMarkers(withoutIdeContext(text));
83
+ }
84
+ export function readablePrompt(prompt) {
85
+ const command = COMMAND_NAME.exec(prompt)?.[1]?.trim();
86
+ if (!command)
87
+ return withoutImageMarkers(withoutIdeContext(prompt));
88
+ const args = COMMAND_ARGS.exec(prompt)?.[1]?.trim() ?? '';
89
+ return args ? `${command} ${args}` : command;
90
+ }
60
91
  export function isSearchable(prompt) {
61
92
  const normalized = prompt.trim().toLowerCase();
62
93
  if (TRIVIAL.has(normalized.replace(/[.!?]+$/, '')))
@@ -36,9 +36,38 @@ for. `claude-db uninstall` takes the block back out.
36
36
  file or ran a real command. Questions, `grep`, and "ok" are skipped. A busy day
37
37
  produces 10 to 20 rows, not hundreds.
38
38
 
39
- **What gets injected.** Recent session summaries at startup, plus the single
40
- best match in full on each prompt. Roughly 350 tokens when something relevant
41
- exists, zero when it doesn't.
39
+ **What gets injected.** Recent session summaries at startup. Above a prompt, at
40
+ most two memories from earlier chats, picked by Claude Haiku:
41
+
42
+ 1. Search finds the ten closest memories from other chats. If none shares at
43
+ least two content words with the prompt, nothing happens and Haiku is not
44
+ called.
45
+ 2. Haiku reads them with the prompt and the end of Claude's previous reply, and
46
+ picks only memories that hold something specific for this task. Most prompts
47
+ get none.
48
+ 3. Each pick carries one sentence copied from the memory. The code checks the
49
+ sentence is really in it, so a pick cannot carry a claim the memory does not
50
+ make.
51
+ 4. The pick runs in the background, so typing is never held up, and reaches
52
+ Claude with its first tool call. A turn that uses no tools does not get it.
53
+
54
+ A line looks like `- Oct 1: asked "why does the order feed drop after a minute?": The
55
+ websocket client sends no heartbeat, so the proxy closes an idle connection after
56
+ 60 seconds. (id)`: the
57
+ day, the question that memory answered, the copied sentence, and the id
58
+ `get_observations` expands. Nothing from the current chat is repeated back to
59
+ it. Subagent reports, task notifications and slash commands are not prompts, so
60
+ they get nothing.
61
+
62
+ At most 150 picks a day (`pick.dailyLimit`), and a failed call pauses picking
63
+ for an hour. Without Haiku (off, over the limit, or paused), only a strong word
64
+ match is shown: the closest memory, if it shares four content words with the
65
+ prompt. `claude-db pick off` turns Haiku off; `claude-db pick` shows today's
66
+ count.
67
+
68
+ **After `/compact`.** Compaction drops the chat's own history, so the start hook
69
+ puts back what this chat decided and what it left uncommitted, under "Earlier in
70
+ this chat".
42
71
 
43
72
  **What search returns.** An id, kind, date, title and one line of the matching
44
73
  body, enough to tell two similarly-titled rows apart without expanding either.
@@ -59,6 +88,43 @@ Files: src/ws/client.ts, src/ws/reconnect.ts
59
88
  Ran: Test run: pnpm test
60
89
  ```
61
90
 
91
+ ## Facts
92
+
93
+ A captured turn is a record of what happened, which makes a poor memory on its
94
+ own: its title is whatever sentence Claude happened to write. So when a chat
95
+ ends, one small Claude Haiku call reads the chat's saved rows, together with the
96
+ facts already known, and writes short facts back: a **rule**, a **decision**
97
+ and its reason, a **dead end**, a **to do**, or a lasting **fact**. A fact has
98
+ a stable key, so a later chat updates it in place, and Haiku retires a fact the
99
+ chat shows is no longer true. The raw rows stay as the evidence.
100
+
101
+ Facts open each chat, as three short sections: about you, this project, and
102
+ where you stopped, each line like `- Decided (Oct 5): All 12 timers fire after
103
+ 1.1s. (id)`. They are also what `search` finds, and they travel with the
104
+ database to other machines. Above a prompt, picks come from earlier chats' rows:
105
+ with Haiku picking from either, a picked fact was useful 60% of the time against
106
+ 69% for a chat's own rows, so facts are not offered there.
107
+
108
+ Only a **rule** about how you like to work is filed under you, keyed by your
109
+ git email, so it follows you into every project and never reaches a teammate
110
+ on a shared database. Everything else stays in its project.
111
+
112
+ The call goes through your own Claude Code login and runs in the background, so
113
+ closing a chat stays instant. At most 30 calls a day; a failed call pauses it
114
+ for a day while capture carries on; a long chat is read in windows of about
115
+ 40,000 characters, one call each. `claude-db distill off` turns it off, and
116
+ `claude-db distill` shows what it has done.
117
+
118
+ Claude Code's own memory files, `~/.claude/projects/<project>/memory/*.md`, are
119
+ imported as facts too, at no AI cost. On the machine where Claude already reads
120
+ them they are not repeated; on another machine sharing the database, they are.
121
+
122
+ **Upgrading.** The first session after an update repairs memory saved under
123
+ older capture rules, once and in the background: every chat that still has a
124
+ transcript is re-saved, and rows the current rules no longer produce are marked
125
+ replaced, kept but left out of search. Older chats are then turned into facts,
126
+ newest first, within the daily limit.
127
+
62
128
  ## Unfinished work
63
129
 
64
130
  A captured turn is stored `open`, and closes when every file it touched has
@@ -0,0 +1,339 @@
1
+ # Setup guide: get the best results from claude-db
2
+
3
+ Last updated: 2026-10-06. This guide describes the version in this repository, including everything
4
+ listed under 0.10.0 in the [changelog](../CHANGELOG.md).
5
+
6
+ claude-db works after one install command. This guide covers what comes after that: how to check it
7
+ is working, how to give it a head start, which habits and settings change the results most, and what
8
+ it costs. Where a recommendation rests on a measurement, the number is given. The measurements are in
9
+ [memory-improvements.md](https://github.com/Avijit07x/claude-db/blob/main/docs/memory-improvements.md), and how it all works is in
10
+ [how-it-works.md](./how-it-works.md).
11
+
12
+ ## The short version
13
+
14
+ 1. Use Node 22.16 or newer, and a git repository.
15
+ 2. `npm install -g claude-db`
16
+ 3. In your project: `claude-db install --project`
17
+ 4. Keep the personal files out of git (`.mcp.json`, `CLAUDE.local.md`).
18
+ 5. Restart Claude Code.
19
+ 6. Check it: `claude-db status` and `claude-db doctor`.
20
+ 7. Give it a head start: `claude-db flush`, `claude-db scan`, `claude-db seed --from-git`.
21
+ 8. Work as usual, and look again with `claude-db status` after a day.
22
+
23
+ The rest of this guide explains each step and what to do after it.
24
+
25
+ ## 1. Requirements
26
+
27
+ | You need | Why |
28
+ | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
29
+ | Node 22.16 or newer | The default database is Node's built-in SQLite. Before 22.16 it either needs a flag or has no full-text search. An older Node is refused at install with a clear message. Check with `node -v` |
30
+ | A git repository | `scan` and `seed` read your project through git, and the project's folder path is what its memory is filed under |
31
+ | Claude Code, logged in | Two background features call Claude Haiku through your own login (see [cost and privacy](#7-cost-and-privacy)). The terminal CLI and the VS Code extension both work |
32
+
33
+ Nothing else is required. Postgres, MongoDB and the local embedding model are optional.
34
+
35
+ ## 2. Install
36
+
37
+ ```bash
38
+ npm install -g claude-db
39
+ cd your-project
40
+ claude-db install --project
41
+ ```
42
+
43
+ Every command also works as `cdb`.
44
+
45
+ ### One project or the whole machine
46
+
47
+ | | `claude-db install --project` | `claude-db install` |
48
+ | ------------------- | ----------------------------------------- | ----------------------------------------------- |
49
+ | Applies to | this repository only | every project you open on this machine |
50
+ | Hooks go in | `.claude/settings.local.json` in the repo | `~/.claude/settings.json` |
51
+ | Memory instructions | `CLAUDE.local.md` in the repo | `~/.claude/CLAUDE.md` |
52
+ | MCP server in | `.mcp.json` in the repo | your Claude Code user config (`~/.claude.json`) |
53
+ | Good for | trying it, or keeping it off some repos | using it everywhere without thinking about it |
54
+
55
+ Memory itself is always one database for the whole machine (`~/.claude-memory/memory.db`), filed by
56
+ project. The choice above only decides where claude-db is switched on.
57
+
58
+ ### What install registers
59
+
60
+ Five hooks, which is why nothing needs to be run by hand afterwards:
61
+
62
+ | Hook | What it does |
63
+ | -------------------------- | ----------------------------------------------------------------------- |
64
+ | SessionStart | Shows what matters at the start of a chat, and starts background upkeep |
65
+ | UserPromptSubmit | Saves the previous turn and looks for memory that fits your new prompt |
66
+ | PreToolUse (every tool) | Hands Claude the memory Haiku picked, with its first tool call |
67
+ | PreToolUse (Bash and Grep) | Points symbol searches at the code graph instead of grep |
68
+ | SessionEnd | Saves the last turn and starts turning the chat into facts |
69
+
70
+ It also writes a standing instruction ("search memory before asking the user to re-explain") and the
71
+ `/cdb-scan` skill.
72
+
73
+ ### Keep personal files out of git
74
+
75
+ `.mcp.json` holds an absolute path on your machine, so committing it breaks the project for everyone
76
+ else. `CLAUDE.local.md` and `.claude/settings.local.json` are meant to be personal too. Make sure all
77
+ three are ignored:
78
+
79
+ ```bash
80
+ printf '\n.mcp.json\nCLAUDE.local.md\n.claude/settings.local.json\n' >> .gitignore
81
+ ```
82
+
83
+ The installer only reminds you about `.mcp.json`, and only when no `.gitignore` lists it.
84
+
85
+ ### Restart Claude Code
86
+
87
+ The MCP server and the hooks are loaded when Claude Code starts. A session that was already open does
88
+ not have them.
89
+
90
+ ## 3. Check that it works
91
+
92
+ ```bash
93
+ claude-db status
94
+ ```
95
+
96
+ Right after install you should see this, with your own paths:
97
+
98
+ ```text
99
+ project : ~/shop
100
+ database : ~/.claude-memory/memory.db
101
+ hooks : this project
102
+ mcp : registered (~/shop/.mcp.json)
103
+ sessions : 0 recorded for this project
104
+ worked : never
105
+ recorded : never
106
+ facts : 0 for this project, 0 about you
107
+ waiting : 0 chat(s) not yet turned into facts
108
+ pick : on (haiku), 0 of 150 picks used today
109
+ ```
110
+
111
+ "Nothing recorded yet" is normal here. Memory is written as you work, only for turns that changed
112
+ something, so a chat of questions leaves nothing behind. After your first real session, `sessions`
113
+ and `recorded` fill in.
114
+
115
+ ```bash
116
+ claude-db doctor
117
+ ```
118
+
119
+ `doctor` shows the version, the database, whether it can be reached, the embedder, and whether the
120
+ hooks are wired once each (`wiring : ok`). `claude-db doctor --deep` goes further: it writes one
121
+ test memory, searches for it, reads it back and deletes it, and tells you which step failed if any.
122
+
123
+ ## 4. Give it a head start
124
+
125
+ A fresh install has nothing to recall. These steps fill it from what already exists.
126
+
127
+ | Step | Command | What it does | Cost |
128
+ | ------------------------------------ | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
129
+ | Load your past chats | `claude-db flush` | Reads the chats Claude Code already saved for this project and turns them into memory. Claude Code keeps chat files for about 30 days, so do this early | none |
130
+ | Map the code | `claude-db scan` | Stores every symbol and how they connect. About a second on a mid-size repo. After the first scan it refreshes itself at each session start | none |
131
+ | Read the git history | `claude-db seed --from-git` | Turns your commit history into memory so search has something to match | none |
132
+ | Or do the mapping from inside Claude | `/cdb-scan` | A skill that builds the graph, then writes five notes about your stack, layout, conventions, workflows and architecture | a normal chat turn |
133
+ | State your standing rules | `claude-db remember "always use pnpm in this repo"` | Stored as a rule for this project and recalled when relevant | none |
134
+
135
+ After you have used it for a session or two, a background job starts turning your older chats into
136
+ **facts**: short rules, decisions with their reasons, dead ends and to-dos. It works newest chat first,
137
+ only on the last 90 days, and at most 30 Haiku calls a day. `claude-db distill` shows how many chats
138
+ are still waiting. Claude Code's own memory files for the project (`~/.claude/projects/*/memory/`) are
139
+ imported as facts too, at no cost.
140
+
141
+ ## 5. Work in ways that help memory
142
+
143
+ These follow from how recall works. The numbers come from replaying 300 real prompts; see
144
+ [memory-improvements.md](https://github.com/Avijit07x/claude-db/blob/main/docs/memory-improvements.md).
145
+
146
+ - **Be specific.** A prompt needs at least two meaningful words, and a past memory is only considered
147
+ if it shares at least two of them with your prompt. "Make the order feed reconnect with backoff"
148
+ finds things. "ok", "continue" and "do it" find nothing, on purpose.
149
+ - **Expect memory with Claude's first tool call, not before your prompt.** Haiku reads the closest
150
+ ten memories and picks at most two, only when they carry something specific for this task. Most
151
+ prompts get none: in testing about 30% did, and about 6 to 7 in 10 of what was shown was judged
152
+ useful. A turn in which Claude uses no tools never shows a pick.
153
+ - **Say why.** "We chose a websocket because polling hammered the API" becomes a decision with its
154
+ reason. "That approach failed because..." becomes a dead end. These are what a later chat needs.
155
+ - **State a rule once, plainly.** Tell Claude to remember it, or run `claude-db remember`.
156
+ - **Commit finished work.** Work that changed files stays listed as "Not committed" in `status` and at
157
+ the start of a chat until those files are committed.
158
+ - **Wrap anything private in `<private>...</private>`.** It is removed before the turn is saved.
159
+ - **Use `/compact` freely.** When a chat is compacted, its own decisions and open work are put back.
160
+ - **Keep `CLAUDE.md` for a stable overview of the project.** claude-db stores what happened, which is
161
+ a different job.
162
+ - **Look at what it holds.** `claude-db search <words>`, `claude-db stats`, and `claude-db view` for a
163
+ page in the browser.
164
+
165
+ ## 6. Settings
166
+
167
+ Settings live in `~/.claude-memory/config.json`. The file is optional and every key has a default.
168
+ It is created the first time a command changes a setting, such as `claude-db pick off`,
169
+ `claude-db distill off` or `claude-db use`. Edit it by hand for the rest, and list only the keys you
170
+ want to change.
171
+
172
+ | Key | Default | What it does | Change it when |
173
+ | ---------------------- | -------- | ---------------------------------------------------------------- | ----------------------------------------------------------- |
174
+ | `pick.enabled` | `true` | Let Haiku pick the memory shown with a prompt | you want no Claude usage for this (`claude-db pick off`) |
175
+ | `pick.dailyLimit` | `150` | Most picks a day. After that, only strong word matches are shown | you work a lot in one day |
176
+ | `pick.model` | `haiku` | `haiku`, `sonnet` or `opus` | almost never; Haiku was the one measured |
177
+ | `distill.enabled` | `true` | Turn finished chats into facts | you want no Claude usage for this (`claude-db distill off`) |
178
+ | `distill.dailyLimit` | `30` | Most fact-making calls a day | you have many old chats to catch up on |
179
+ | `distill.backfillDays` | `90` | How far back older chats are turned into facts | you want a shorter or longer reach |
180
+ | `inject.perPrompt` | `true` | Show related memory with prompts at all | you want memory only at the start of a chat |
181
+ | `inject.minOverlap` | `2` | Meaningful words a memory must share with the prompt | almost never; 2 was the best floor measured |
182
+ | `inject.promptResults` | `2` | Most memories shown with one prompt | you want more or fewer lines |
183
+ | `updates` | `notify` | `notify`, `auto` or `off` | you want updates installed for you, or never checked |
184
+ | `embeddings.provider` | `auto` | `auto`, `local`, `builtin` or `none` | you install the optional embedding model, or want none |
185
+
186
+ ### Three ready-made setups
187
+
188
+ **The default** needs no file. It uses Haiku for picking and for facts, inside the daily limits.
189
+
190
+ **No Claude usage.** Memory is still recorded and searched, but nothing calls Claude:
191
+
192
+ ```json
193
+ {
194
+ "pick": { "enabled": false },
195
+ "distill": { "enabled": false }
196
+ }
197
+ ```
198
+
199
+ The cost is quality. Without Haiku, a prompt only gets memory when the closest one shares four
200
+ meaningful words with it. In testing that showed memory on about 12% of prompts, and it was useful
201
+ 43% of the time, against about 6 to 7 in 10 with Haiku. No new facts are made, so the start of a
202
+ chat shows the facts it already has, or recent session summaries if there are none.
203
+
204
+ **Heavy use.** Raise the limits if you hit them. `claude-db pick` and `claude-db distill` show how
205
+ much of today's limit is used:
206
+
207
+ ```json
208
+ {
209
+ "pick": { "dailyLimit": 400 },
210
+ "distill": { "dailyLimit": 60 }
211
+ }
212
+ ```
213
+
214
+ ### Better embeddings are optional
215
+
216
+ The built-in embedder works without installing anything. For semantic matching in `search`:
217
+
218
+ ```bash
219
+ npm install -g @xenova/transformers
220
+ claude-db reembed
221
+ ```
222
+
223
+ This is a large download (about 200 MB of libraries plus a model). It is not needed for picking, and
224
+ its effect on the memory shown with prompts was not measured.
225
+
226
+ ## 7. Cost and privacy
227
+
228
+ Nothing leaves your machine except the things below, and each can be turned off.
229
+
230
+ | What | When | What is sent | Cost | Limit | Turn it off |
231
+ | ------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ---------- | ----------------------- |
232
+ | Picking | A prompt has related memory | Your prompt, the end of Claude's previous reply, and up to ten memory excerpts of 600 characters, all redacted | About 3,000 input and 100 output Haiku tokens per pick | 150 a day | `claude-db pick off` |
233
+ | Facts | After a chat ends | The chat's saved, redacted text, in pieces of about 40,000 characters | One Haiku call per piece | 30 a day | `claude-db distill off` |
234
+ | Update check | Once a day | A request to the npm registry | none | once a day | `"updates": "off"` |
235
+ | Your database | Only if you set a remote one | Your memory | depends on the host | none | `claude-db use <path>` |
236
+
237
+ Both Haiku features go through your own Claude Code login, so they count against your plan like any
238
+ other use. Haiku is the lightest model, and a pick is small next to an ordinary chat turn. A failed
239
+ call pauses that feature, for an hour for picking and a day for facts, while recording carries on.
240
+
241
+ What is never stored: `.env` files, anything under `secrets/`, `node_modules` and `.git/`. Text in
242
+ `<private>...</private>` is stripped. API keys, tokens, private keys, connection-string passwords and
243
+ `NAME=value` secrets are redacted before anything is saved or sent. `claude-db redact` re-applies the
244
+ current rules to memory saved earlier; it also runs once on its own after an update.
245
+
246
+ One limit to know about: a secret you paste into a chat also stays in Claude Code's own chat file,
247
+ which claude-db does not edit. If you paste a real secret, rotate it.
248
+
249
+ ## 8. Teams and several machines
250
+
251
+ SQLite is the default and needs no setup. To share memory, point claude-db at a database everyone can
252
+ reach:
253
+
254
+ ```bash
255
+ npm install -g pg
256
+ claude-db use "postgres://user:pass@host:5432/memory"
257
+ ```
258
+
259
+ Use `mongodb` and a `mongodb+srv://` address for MongoDB. Install the driver the same way claude-db
260
+ was installed, since neither ships by default. `use` checks the database answers before it saves the
261
+ address, and warns if the database already holds tables that are not claude-db's. Give it a database
262
+ of its own.
263
+
264
+ - **Projects are matched by folder path.** Two machines share a project's memory when the project is
265
+ at the same path on both. If a repository lives at a different path on another machine, run
266
+ `claude-db merge <old-path> --yes` from the new location to bring the old memory across.
267
+ - **Personal rules stay personal.** A rule about how you like to work is filed under your git email,
268
+ so it follows you into every project and never reaches a teammate on a shared database. Set
269
+ `git config user.email` so it is filed under the right name. Everything else belongs to the
270
+ project and is shared.
271
+ - **Two databases, one memory.** `claude-db sync <url>` merges two databases in both directions, so a
272
+ laptop and a desktop can each work offline and reconcile later. `claude-db export` and
273
+ `claude-db import` do the same with a file.
274
+ - **Use a restricted account.** Connection strings are redacted whenever claude-db prints them, but
275
+ the account should only be able to reach its own database.
276
+
277
+ ## 9. Keep it healthy
278
+
279
+ | How often | Command | Why |
280
+ | ------------------------- | ---------------------------------- | --------------------------------------------------------------------- |
281
+ | Now and then | `claude-db status` | Wired up, last recorded, open work, how many picks used today |
282
+ | Now and then | `claude-db stats` | What memory is made of, by kind and by area |
283
+ | After a big refactor | `claude-db scan` | Refreshes the code graph (it also refreshes at each session start) |
284
+ | When memory is stale | `claude-db prune --older-than 180` | A dry run that counts what would go; add `--yes` to delete |
285
+ | When something is wrong | `claude-db forget <id>` | Deletes a memory that turned out to be wrong, so it stops coming back |
286
+ | After moving a repository | `claude-db merge <old-path> --yes` | Brings memory filed under the old path across |
287
+
288
+ `claude-db uninstall --project` removes the hooks, the MCP entry and the instructions, and leaves your
289
+ memory untouched. Only `forget`, `prune` and `reset` delete memory, and the last two do nothing without
290
+ `--yes`.
291
+
292
+ ## 10. Upgrading
293
+
294
+ ```bash
295
+ npm install -g claude-db
296
+ ```
297
+
298
+ or `claude-db update`. Then restart Claude Code once. At the first session after an update, a few
299
+ one-time jobs may run in the background, and none of them blocks a chat:
300
+
301
+ - repairing memory that an older version saved badly (`claude-db flush --repair`),
302
+ - re-applying secret redaction to everything already saved (`claude-db redact`),
303
+ - turning older chats into facts, which carries on over the next sessions within the daily limit.
304
+
305
+ Hooks that an earlier install registered are brought up to date automatically at session start, so a
306
+ new hook arrives without running `install` again. The first chat after you get facts says so once, and
307
+ how to switch that off with `claude-db distill off`.
308
+
309
+ ## 11. When something is off
310
+
311
+ | What you see | Check |
312
+ | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
313
+ | Nothing is recorded | Did you restart Claude Code after installing? Was `install` run in this repository? Did any turn change a file? Questions and read-only commands are skipped by design |
314
+ | Memory rarely shows up | Early on there is little to find, so run the head start steps in section 4. Prompts of one or two words, or filler, get none. Run `claude-db pick`: it says if picking is off, paused after a failed call, or past today's limit |
315
+ | Memory never shows in a chat of questions | Picks arrive with Claude's first tool call, so a turn with no tools never shows one |
316
+ | `doctor` says `registered 2x` | Run `claude-db install` again. It replaces its own entries |
317
+ | Install stops with a Node version message | Upgrade to Node 22.16 or newer |
318
+ | `reachable: no` | For Postgres or MongoDB, install the driver (`npm install -g pg` or `npm install -g mongodb`) and check `CLAUDE_DB_URL` is not set to something old |
319
+ | A moved repository looks empty | Memory is filed by folder path. Run `claude-db merge <old-path> --yes` |
320
+ | Search got worse after adding the embedding model | Run `claude-db reembed` |
321
+
322
+ The [troubleshooting page](https://claude-db.vercel.app/docs/troubleshooting) covers the rest.
323
+
324
+ ## 12. Where things live
325
+
326
+ | Path | What it is |
327
+ | --------------------------------------- | ----------------------------------------------------------------------- |
328
+ | `~/.claude-memory/memory.db` | The default SQLite database |
329
+ | `~/.claude-memory/config.json` | Your settings (optional) |
330
+ | `~/.claude-memory/cursors/` | How far each chat has been read, and what a chat has already been shown |
331
+ | `~/.claude-memory/pick/` | Picks in flight and today's pick count |
332
+ | `~/.claude-memory/distill/` | Today's fact-making count |
333
+ | `~/.claude-memory/reingest/`, `redact/` | Marks that a one-time job has finished, per project or database |
334
+ | `.claude/settings.local.json` | The hooks, for a project install |
335
+ | `.mcp.json` | The MCP server, for a project install |
336
+ | `CLAUDE.local.md` | The standing instruction to search memory |
337
+ | `.claude/skills/cdb-scan/` | The `/cdb-scan` skill |
338
+
339
+ To delete everything claude-db has stored, remove `~/.claude-memory`.