claude-db 0.9.1 → 0.10.1
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 +248 -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 +27 -5
- 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
|
@@ -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;
|
package/dist/util/day.js
ADDED
|
@@ -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
|
+
}
|
package/dist/util/prompt.d.ts
CHANGED
|
@@ -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;
|
package/dist/util/prompt.js
CHANGED
|
@@ -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(/[.!?]+$/, '')))
|
package/docs/how-it-works.md
CHANGED
|
@@ -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
|
|
40
|
-
|
|
41
|
-
|
|
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`.
|