claude-db 0.11.0 → 0.11.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 +27 -0
- package/README.md +41 -79
- package/dist/catchup/gather.d.ts +1 -0
- package/dist/catchup/gather.js +9 -2
- package/dist/catchup/git-state.d.ts +2 -0
- package/dist/catchup/git-state.js +3 -0
- package/dist/catchup/render.js +8 -0
- package/dist/cli/files.d.ts +2 -0
- package/dist/cli/files.js +15 -1
- package/dist/cli/install.js +4 -3
- package/dist/cli/skills.js +6 -1
- package/dist/facts/distill.d.ts +0 -2
- package/dist/facts/distill.js +4 -26
- package/dist/facts/handoff.js +11 -1
- package/dist/facts/known.d.ts +4 -0
- package/dist/facts/known.js +38 -0
- package/dist/facts/ops.d.ts +1 -1
- package/dist/facts/ops.js +4 -2
- package/dist/facts/start.js +5 -1
- package/docs/setup-guide.md +47 -299
- package/package.json +2 -2
- package/skills/catchup/SKILL.md +2 -0
- package/skills/handoff/SKILL.md +23 -7
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,32 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.11.1
|
|
4
|
+
|
|
5
|
+
### Fixed
|
|
6
|
+
|
|
7
|
+
- **Facts no longer repeat a rule you saved by hand.** When a chat ended, the fact-making call saw the
|
|
8
|
+
earlier facts but not the rules you saved with `remember`, so it saved the same rule again and the start
|
|
9
|
+
of a chat listed it twice. The call now sees those rules and is told not to repeat them. Rules already
|
|
10
|
+
duplicated stay until you remove one with `claude-db forget <id>`.
|
|
11
|
+
- **`uninstall --project` leaves nothing empty behind.** It used to leave an empty `.mcp.json` and
|
|
12
|
+
`.claude/settings.local.json`, and an empty `.claude/skills` folder. It now removes them when nothing else
|
|
13
|
+
is in them. Your own settings, servers and skills are never touched, and a machine-wide uninstall is
|
|
14
|
+
unchanged.
|
|
15
|
+
|
|
16
|
+
### Changed
|
|
17
|
+
|
|
18
|
+
- **`/handoff` keeps more, in a fixed size.** The note can now hold Decided, Rejected, Watch out and State
|
|
19
|
+
lines, with the reason after "because", and carries still-true lines forward. It is capped at 8 lines of
|
|
20
|
+
about 200 characters. At the start of a chat only those 8 lines are shown, each cut at 220 characters, with
|
|
21
|
+
a line saying how many more there are. The first line ends with the note's id, so the full text can be
|
|
22
|
+
read with `get_observations`.
|
|
23
|
+
- **`/catchup` shows the branch and how many files are uncommitted**, and the recent decisions and dead
|
|
24
|
+
ends, so a handoff can be written from facts and not only from the chat.
|
|
25
|
+
|
|
26
|
+
### Docs
|
|
27
|
+
|
|
28
|
+
- A shorter setup guide and README, and a cleaner docs site with a Skills page and a clearer code block.
|
|
29
|
+
|
|
3
30
|
## 0.11.0
|
|
4
31
|
|
|
5
32
|
### Added
|
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
<img src="./assets/wordmark.svg" alt="claude-db" width="330">
|
|
2
2
|
|
|
3
|
-
**
|
|
3
|
+
**Free, open-source memory for Claude Code. Your own database, no cloud, no subscription.**
|
|
4
4
|
|
|
5
5
|
[](https://www.npmjs.com/package/claude-db)
|
|
6
6
|
[](https://github.com/Avijit07x/claude-db/actions/workflows/ci.yml)
|
|
@@ -12,112 +12,74 @@
|
|
|
12
12
|
|
|
13
13
|
---
|
|
14
14
|
|
|
15
|
-
##
|
|
15
|
+
## Why
|
|
16
16
|
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
Claude knows none of it, so you explain it again.
|
|
17
|
+
Every Claude Code chat starts from zero. You explain the same decisions, dead
|
|
18
|
+
ends and rules again, and Claude works out what calls what from scratch.
|
|
20
19
|
|
|
21
|
-
claude-db
|
|
22
|
-
|
|
20
|
+
claude-db fixes that. It keeps what you decided and a map of your code, and
|
|
21
|
+
gives Claude the right part of it at the right time.
|
|
23
22
|
|
|
24
|
-
## What
|
|
23
|
+
## What it does
|
|
25
24
|
|
|
26
|
-
- **
|
|
27
|
-
|
|
28
|
-
- **
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
memory across machines. No cloud, no subscription.
|
|
25
|
+
- **Remembers across chats.** Decisions, dead ends and rules are saved when a
|
|
26
|
+
chat ends, and the next chat starts by seeing them.
|
|
27
|
+
- **Recalls what fits.** Each prompt gets the one or two earlier memories that
|
|
28
|
+
match it, and nothing when none fit.
|
|
29
|
+
- **Maps your code.** Who defines or calls a symbol is answered in one call,
|
|
30
|
+
instead of grep and reading files.
|
|
31
|
+
- **Keeps it yours.** SQLite on your machine by default, or Postgres or MongoDB
|
|
32
|
+
to share across machines. No cloud, no subscription.
|
|
35
33
|
|
|
36
34
|
## Install
|
|
37
35
|
|
|
36
|
+
You need Node 22.16 or newer and a git repository.
|
|
37
|
+
|
|
38
38
|
```bash
|
|
39
39
|
npm install -g claude-db
|
|
40
|
-
|
|
41
40
|
cd your-project
|
|
42
41
|
claude-db install --project
|
|
43
42
|
```
|
|
44
43
|
|
|
45
|
-
Restart Claude Code.
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
`--project` limits it to this repo instead of every project on the machine. Add
|
|
49
|
-
`.mcp.json` to your `.gitignore`, since it holds a path that only exists on your
|
|
50
|
-
machine.
|
|
51
|
-
|
|
52
|
-
A fresh install has no history yet. `claude-db scan` builds the code graph, and
|
|
53
|
-
the `/cdb-scan` skill maps an existing codebase into memory, so search has
|
|
54
|
-
something to find on day one. `/catchup` answers "where did I stop?" and `/handoff` leaves a note for the
|
|
55
|
-
next chat. The [setup guide](./docs/setup-guide.md) covers
|
|
56
|
-
the settings and habits that give the best results.
|
|
57
|
-
|
|
58
|
-
## Commands
|
|
59
|
-
|
|
60
|
-
`cdb` is a shorter alias for all of them.
|
|
44
|
+
Restart Claude Code. There is nothing else to run, because capture and recall
|
|
45
|
+
are hooks.
|
|
61
46
|
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
| `claude-db install [--project]` | Register the hooks and the MCP server |
|
|
65
|
-
| `claude-db status` | Is it wired up, and when did it last record anything |
|
|
66
|
-
| `claude-db doctor [--deep]` | Show the resolved config; `--deep` tests a round trip |
|
|
67
|
-
| `claude-db scan` | Build the code graph for this repo |
|
|
68
|
-
| `claude-db use <url>` | Switch database and verify it |
|
|
69
|
-
| `claude-db distill [on\|off]` | Turn chats into facts with Haiku |
|
|
70
|
-
| `claude-db pick [on\|off]` | Let Haiku pick the memory shown with each prompt |
|
|
71
|
-
| `claude-db view` | See this project's memory in the browser |
|
|
47
|
+
Then load what already exists with `claude-db flush` and `claude-db scan`. The
|
|
48
|
+
[setup guide](./docs/setup-guide.md) has the rest.
|
|
72
49
|
|
|
73
|
-
|
|
74
|
-
the [CLI reference](https://claude-db.vercel.app/docs/cli).
|
|
50
|
+
## Everyday use
|
|
75
51
|
|
|
76
|
-
|
|
52
|
+
| Where | What it does |
|
|
53
|
+
| --------------------- | ------------------------------------------------- |
|
|
54
|
+
| `/catchup` | Answers "where did I stop?" when you come back |
|
|
55
|
+
| `/handoff` | Leaves a short note for the next chat or a mate |
|
|
56
|
+
| `/cdb-scan` | Maps an existing codebase into memory |
|
|
57
|
+
| `claude-db status` | Shows whether it is wired up and what it recorded |
|
|
58
|
+
| `claude-db doctor` | Checks the setup, and finds what is wrong |
|
|
59
|
+
| `claude-db use <url>` | Switches to Postgres or MongoDB (`pg`/`mongodb`) |
|
|
77
60
|
|
|
78
|
-
|
|
79
|
-
claude-db
|
|
80
|
-
claude-db use "mongodb+srv://user:pass@cluster.mongodb.net/memory"
|
|
81
|
-
```
|
|
82
|
-
|
|
83
|
-
Install the driver first, with `npm install -g pg` or `npm install -g mongodb`.
|
|
84
|
-
Neither ships by default.
|
|
61
|
+
`cdb` is a shorter alias. Every command is in the
|
|
62
|
+
[CLI reference](https://claude-db.vercel.app/docs/cli).
|
|
85
63
|
|
|
86
64
|
## Privacy
|
|
87
65
|
|
|
88
|
-
Memory stays in your own database.
|
|
89
|
-
an off switch:
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
through your own login, to make facts. Turn it off with `claude-db distill off`.
|
|
93
|
-
- **When a prompt has related memory**, the prompt, the end of Claude's last
|
|
94
|
-
reply and up to ten saved excerpts go to Haiku, so it can pick what to show.
|
|
95
|
-
Turn it off with `claude-db pick off`.
|
|
96
|
-
- **Once a day**, the npm registry is asked for the latest version. Turn it off
|
|
97
|
-
with `"updates": "off"` in the config.
|
|
66
|
+
Memory stays in your own database. Two features call Claude Haiku through your
|
|
67
|
+
own login, and each has an off switch: `claude-db distill off` for making facts
|
|
68
|
+
from finished chats, and `claude-db pick off` for choosing memory per prompt.
|
|
69
|
+
Once a day it asks npm for the latest version (`"updates": "off"` stops that).
|
|
98
70
|
|
|
99
71
|
`.env`, `secrets/`, `node_modules` and `.git/` are never stored. Text inside
|
|
100
72
|
`<private>...</private>` is stripped, and API keys and tokens are redacted
|
|
101
73
|
before anything is written or sent.
|
|
102
74
|
|
|
103
|
-
## Requirements
|
|
104
|
-
|
|
105
|
-
Node 22.16 or newer. SQLite comes from Node's builtin `node:sqlite`, so nothing
|
|
106
|
-
compiles at install time. For real semantic search, run
|
|
107
|
-
`npm install -g @xenova/transformers` and the embedder upgrades itself.
|
|
108
|
-
|
|
109
75
|
## Documentation
|
|
110
76
|
|
|
111
|
-
- [
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
[how it works](https://claude-db.vercel.app/docs/how-it-works),
|
|
115
|
-
[databases](https://claude-db.vercel.app/docs/databases) and
|
|
116
|
-
[troubleshooting](https://claude-db.vercel.app/docs/troubleshooting)
|
|
117
|
-
- [Setup guide](./docs/setup-guide.md): settings, habits and costs
|
|
77
|
+
- [Setup guide](./docs/setup-guide.md): install, head start and habits
|
|
78
|
+
- [Documentation site](https://claude-db.vercel.app/docs): CLI, MCP tools,
|
|
79
|
+
databases and troubleshooting
|
|
118
80
|
- [With and without](./docs/with-and-without.md) and
|
|
119
|
-
[benchmarks](https://claude-db.vercel.app/docs/benchmarks):
|
|
120
|
-
including
|
|
81
|
+
[benchmarks](https://claude-db.vercel.app/docs/benchmarks): the numbers,
|
|
82
|
+
including where plain grep wins
|
|
121
83
|
- [Changelog](./CHANGELOG.md)
|
|
122
84
|
|
|
123
85
|
## Contributing
|
package/dist/catchup/gather.d.ts
CHANGED
package/dist/catchup/gather.js
CHANGED
|
@@ -1,10 +1,11 @@
|
|
|
1
1
|
import { openWork } from '../capture/progress.js';
|
|
2
|
-
import { FACT_SESSION, factType, onePerKey } from '../facts/model.js';
|
|
2
|
+
import { FACT_SESSION, factLabel, factType, onePerKey } from '../facts/model.js';
|
|
3
3
|
import { handoffBodyLines, newestHandoff } from '../facts/handoff.js';
|
|
4
4
|
import { readGitState } from './git-state.js';
|
|
5
5
|
const CHAT_TITLES = 6;
|
|
6
6
|
const TODOS = 5;
|
|
7
7
|
const UNCOMMITTED = 5;
|
|
8
|
+
const DECISIONS = 5;
|
|
8
9
|
const FACTS_SCANNED = 100;
|
|
9
10
|
export async function gatherCatchup(ctx, project, now = Date.now()) {
|
|
10
11
|
const handoff = await newestHandoff(ctx, project, now);
|
|
@@ -20,10 +21,15 @@ export async function gatherCatchup(ctx, project, now = Date.now()) {
|
|
|
20
21
|
newest: true,
|
|
21
22
|
limit: FACTS_SCANNED,
|
|
22
23
|
});
|
|
23
|
-
const
|
|
24
|
+
const current = onePerKey(facts.filter((obs) => obs.status !== 'replaced'));
|
|
25
|
+
const todos = current
|
|
24
26
|
.filter((obs) => factType(obs) === 'todo')
|
|
25
27
|
.slice(0, TODOS)
|
|
26
28
|
.map((obs) => obs.title);
|
|
29
|
+
const decisions = current
|
|
30
|
+
.filter((obs) => ['decision', 'deadend'].includes(factType(obs) ?? ''))
|
|
31
|
+
.slice(0, DECISIONS)
|
|
32
|
+
.map((obs) => `${factLabel(obs)}: ${obs.title}`);
|
|
27
33
|
const uncommitted = (await openWork(ctx.store, project))
|
|
28
34
|
.slice(0, UNCOMMITTED)
|
|
29
35
|
.map((obs) => obs.title);
|
|
@@ -33,6 +39,7 @@ export async function gatherCatchup(ctx, project, now = Date.now()) {
|
|
|
33
39
|
? { at: latest.startedAt, summary: latest.summary ?? '', work: chatWork }
|
|
34
40
|
: null,
|
|
35
41
|
todos,
|
|
42
|
+
decisions,
|
|
36
43
|
uncommitted,
|
|
37
44
|
git: readGitState(project),
|
|
38
45
|
};
|
|
@@ -19,8 +19,11 @@ function lines(text) {
|
|
|
19
19
|
export function readGitState(project, git = runGit(project)) {
|
|
20
20
|
try {
|
|
21
21
|
const status = lines(git(['status', '--short']));
|
|
22
|
+
const branch = lines(git(['branch', '--show-current']))[0] ?? null;
|
|
22
23
|
const commits = lines(git(['log', `-n${RECENT_COMMITS}`, '--pretty=format:%h %s'])).map(redact);
|
|
23
24
|
return {
|
|
25
|
+
branch,
|
|
26
|
+
changed: status.length,
|
|
24
27
|
status: status.slice(0, STATUS_LINES),
|
|
25
28
|
hiddenStatusLines: Math.max(0, status.length - STATUS_LINES),
|
|
26
29
|
commits,
|
package/dist/catchup/render.js
CHANGED
|
@@ -16,6 +16,12 @@ function gitLines(data) {
|
|
|
16
16
|
commits: git.commits.map((line) => ` ${line}`),
|
|
17
17
|
};
|
|
18
18
|
}
|
|
19
|
+
function branchLine(git) {
|
|
20
|
+
if (!git)
|
|
21
|
+
return [];
|
|
22
|
+
const state = git.changed === 0 ? 'clean' : `${git.changed} file${git.changed === 1 ? '' : 's'} uncommitted`;
|
|
23
|
+
return [`Branch: ${git.branch ?? 'detached HEAD'}, ${state}`, ''];
|
|
24
|
+
}
|
|
19
25
|
function chatBlock(chat, now) {
|
|
20
26
|
if (!chat)
|
|
21
27
|
return [];
|
|
@@ -33,7 +39,9 @@ export function renderCatchup(data, now = Date.now()) {
|
|
|
33
39
|
...handoffBlock(data.handoff, now),
|
|
34
40
|
...chatBlock(data.lastChat, now),
|
|
35
41
|
...section('Still to do (from facts):', bullets(data.todos)),
|
|
42
|
+
...section('Decisions and dead ends (from facts):', bullets(data.decisions)),
|
|
36
43
|
...section('Not committed yet (recorded work):', bullets(data.uncommitted)),
|
|
44
|
+
...branchLine(data.git),
|
|
37
45
|
...section('Git status:', status),
|
|
38
46
|
...section('Recent commits:', commits),
|
|
39
47
|
];
|
package/dist/cli/files.d.ts
CHANGED
|
@@ -2,3 +2,5 @@ export declare function readText(path: string): string;
|
|
|
2
2
|
export declare function writeAtomic(path: string, content: string): void;
|
|
3
3
|
export declare function readJson(path: string): Record<string, unknown>;
|
|
4
4
|
export declare function writeJson(path: string, value: unknown): void;
|
|
5
|
+
export declare function writeJsonOrRemove(path: string, value: Record<string, unknown>): void;
|
|
6
|
+
export declare function removeIfEmpty(path: string): void;
|
package/dist/cli/files.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { dirname } from 'node:path';
|
|
2
|
-
import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
|
|
2
|
+
import { mkdirSync, readFileSync, renameSync, rmSync, rmdirSync, writeFileSync } from 'node:fs';
|
|
3
3
|
export function readText(path) {
|
|
4
4
|
try {
|
|
5
5
|
return readFileSync(path, 'utf8');
|
|
@@ -31,3 +31,17 @@ export function readJson(path) {
|
|
|
31
31
|
export function writeJson(path, value) {
|
|
32
32
|
writeAtomic(path, `${JSON.stringify(value, null, 2)}\n`);
|
|
33
33
|
}
|
|
34
|
+
export function writeJsonOrRemove(path, value) {
|
|
35
|
+
if (Object.keys(value).length === 0)
|
|
36
|
+
rmSync(path, { force: true });
|
|
37
|
+
else
|
|
38
|
+
writeJson(path, value);
|
|
39
|
+
}
|
|
40
|
+
export function removeIfEmpty(path) {
|
|
41
|
+
try {
|
|
42
|
+
rmdirSync(path);
|
|
43
|
+
}
|
|
44
|
+
catch {
|
|
45
|
+
return;
|
|
46
|
+
}
|
|
47
|
+
}
|
package/dist/cli/install.js
CHANGED
|
@@ -2,7 +2,7 @@ import { instructionsPathFor, mcpPathFor, settingsPathFor } from './paths.js';
|
|
|
2
2
|
import { installSkills, removeSkills } from './skills.js';
|
|
3
3
|
import { resolve } from 'node:path';
|
|
4
4
|
import { execFileSync } from 'node:child_process';
|
|
5
|
-
import { readJson, writeJson } from './files.js';
|
|
5
|
+
import { readJson, writeJson, writeJsonOrRemove } from './files.js';
|
|
6
6
|
import { removeInstructions, writeInstructions } from './instructions.js';
|
|
7
7
|
import { toPosix } from '../util/paths.js';
|
|
8
8
|
const HOOKS = [
|
|
@@ -104,6 +104,7 @@ export function uninstall(distDir, scope, project) {
|
|
|
104
104
|
const settings = readJson(path);
|
|
105
105
|
if (Object.keys(settings).length === 0)
|
|
106
106
|
return null;
|
|
107
|
+
const save = scope === 'project' ? writeJsonOrRemove : writeJson;
|
|
107
108
|
const hooks = (settings['hooks'] ?? {});
|
|
108
109
|
for (const [event, entries] of Object.entries(hooks)) {
|
|
109
110
|
const kept = withoutOurHooks(entries);
|
|
@@ -116,7 +117,7 @@ export function uninstall(distDir, scope, project) {
|
|
|
116
117
|
settings['hooks'] = hooks;
|
|
117
118
|
else
|
|
118
119
|
delete settings['hooks'];
|
|
119
|
-
|
|
120
|
+
save(path, settings);
|
|
120
121
|
removeInstructions(instructionsPathFor(scope, project));
|
|
121
122
|
removeSkills(scope, project);
|
|
122
123
|
if (scope === 'global' && claudeMcp(['mcp', 'remove', 'memory', '-s', 'user'])) {
|
|
@@ -132,7 +133,7 @@ export function uninstall(distDir, scope, project) {
|
|
|
132
133
|
else
|
|
133
134
|
delete mcpConfig['mcpServers'];
|
|
134
135
|
if (existed)
|
|
135
|
-
|
|
136
|
+
save(mcpPath, mcpConfig);
|
|
136
137
|
return path;
|
|
137
138
|
}
|
|
138
139
|
function hookCommand(distDir, file) {
|
package/dist/cli/skills.js
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { rmSync } from 'node:fs';
|
|
2
2
|
import { dirname, resolve } from 'node:path';
|
|
3
|
-
import { readText, writeAtomic } from './files.js';
|
|
3
|
+
import { readText, removeIfEmpty, writeAtomic } from './files.js';
|
|
4
4
|
import { skillPathFor } from './paths.js';
|
|
5
5
|
export const SKILL_MARKER = 'Shipped with claude-db.';
|
|
6
6
|
export const SKILLS = [
|
|
@@ -52,6 +52,11 @@ export function removeSkills(scope, project) {
|
|
|
52
52
|
continue;
|
|
53
53
|
rmSync(dirname(path), { recursive: true, force: true });
|
|
54
54
|
}
|
|
55
|
+
if (scope !== 'project')
|
|
56
|
+
return;
|
|
57
|
+
const skillsDir = dirname(dirname(skillPathFor(scope, project)));
|
|
58
|
+
removeIfEmpty(skillsDir);
|
|
59
|
+
removeIfEmpty(dirname(skillsDir));
|
|
55
60
|
}
|
|
56
61
|
export function describeSkills(project) {
|
|
57
62
|
const scopes = ['project', 'global'];
|
package/dist/facts/distill.d.ts
CHANGED
|
@@ -1,7 +1,6 @@
|
|
|
1
1
|
import type { RecallContext } from '../context.js';
|
|
2
2
|
import type { Observation } from '../types.js';
|
|
3
3
|
import type { HeadlessResult } from '../util/claude-cli.js';
|
|
4
|
-
import type { ExistingFact } from './ops.js';
|
|
5
4
|
export declare const FACTS_JOB = "facts";
|
|
6
5
|
export type Runner = (prompt: string, model: string, timeoutMs: number) => Promise<HeadlessResult>;
|
|
7
6
|
export type DistillOutcome = 'distilled' | 'empty' | 'over-budget' | 'failed';
|
|
@@ -33,7 +32,6 @@ export declare function distillSession(ctx: RecallContext, project: string, sess
|
|
|
33
32
|
export declare function pendingSessions(ctx: RecallContext, project: string, now?: number): Promise<string[]>;
|
|
34
33
|
export declare function oldestPendingAt(ctx: RecallContext, project: string, now?: number): Promise<number | null>;
|
|
35
34
|
export declare function backfill(ctx: RecallContext, project: string, run?: Runner, onStep?: (step: BackfillStep) => void): Promise<BackfillResult>;
|
|
36
|
-
export declare function existingFacts(ctx: RecallContext, project: string): Promise<ExistingFact[]>;
|
|
37
35
|
export declare function chatWindows(rows: Observation[], most?: number): string[];
|
|
38
36
|
export declare function factCounts(ctx: RecallContext, project: string): Promise<{
|
|
39
37
|
project: number;
|
package/dist/facts/distill.js
CHANGED
|
@@ -2,7 +2,8 @@ import { embedObservations } from '../capture/flush.js';
|
|
|
2
2
|
import { runHeadlessResult } from '../util/claude-cli.js';
|
|
3
3
|
import { formatDay } from '../util/day.js';
|
|
4
4
|
import { recordDistillFailure, recordDistillSuccess, takeDistillCalls } from './budget.js';
|
|
5
|
-
import { FACT_SESSION, factId,
|
|
5
|
+
import { FACT_SESSION, factId, factToObservation, youScope } from './model.js';
|
|
6
|
+
import { existingFacts, notedByUser } from './known.js';
|
|
6
7
|
import { buildDistillPrompt, parseOps } from './ops.js';
|
|
7
8
|
export const FACTS_JOB = 'facts';
|
|
8
9
|
const DAY_MS = 24 * 60 * 60 * 1000;
|
|
@@ -10,7 +11,6 @@ const WINDOW_CHARS = 40_000;
|
|
|
10
11
|
const MAX_WINDOWS = 6;
|
|
11
12
|
const ROW_CHARS = 900;
|
|
12
13
|
const SEPARATOR = '\n\n---\n\n';
|
|
13
|
-
const EXISTING_LIMIT = 80;
|
|
14
14
|
const SESSION_ROWS = 1000;
|
|
15
15
|
const TIMEOUT_MS = 120_000;
|
|
16
16
|
export async function distillSession(ctx, project, sessionId, run = runHeadlessResult) {
|
|
@@ -47,7 +47,8 @@ export async function distillSession(ctx, project, sessionId, run = runHeadlessR
|
|
|
47
47
|
}
|
|
48
48
|
async function distillWindow(ctx, project, chat, source, at, run) {
|
|
49
49
|
const existing = await existingFacts(ctx, project);
|
|
50
|
-
const
|
|
50
|
+
const noted = await notedByUser(ctx, project);
|
|
51
|
+
const reply = await run(buildDistillPrompt(chat, existing, noted), ctx.config.distill.model, TIMEOUT_MS);
|
|
51
52
|
if (!reply.ok)
|
|
52
53
|
return { ok: false, reason: reply.reason };
|
|
53
54
|
const ops = parseOps(reply.stdout);
|
|
@@ -96,29 +97,6 @@ export async function backfill(ctx, project, run = runHeadlessResult, onStep = (
|
|
|
96
97
|
}
|
|
97
98
|
return { distilled, facts, remaining: 0, stopped: 'done' };
|
|
98
99
|
}
|
|
99
|
-
export async function existingFacts(ctx, project) {
|
|
100
|
-
const owners = [
|
|
101
|
-
[project, 'project'],
|
|
102
|
-
[youScope(), 'you'],
|
|
103
|
-
];
|
|
104
|
-
const facts = [];
|
|
105
|
-
for (const [owner, scope] of owners) {
|
|
106
|
-
const rows = await ctx.store.list({
|
|
107
|
-
project: owner,
|
|
108
|
-
sessionId: FACT_SESSION,
|
|
109
|
-
newest: true,
|
|
110
|
-
limit: EXISTING_LIMIT,
|
|
111
|
-
});
|
|
112
|
-
for (const obs of onePerKey(rows.filter((row) => row.status !== 'replaced'))) {
|
|
113
|
-
const key = factKey(obs);
|
|
114
|
-
const type = factType(obs);
|
|
115
|
-
if (obs.status === 'replaced' || !key || !type)
|
|
116
|
-
continue;
|
|
117
|
-
facts.push({ key, type, scope, text: obs.title });
|
|
118
|
-
}
|
|
119
|
-
}
|
|
120
|
-
return facts;
|
|
121
|
-
}
|
|
122
100
|
export function chatWindows(rows, most = MAX_WINDOWS) {
|
|
123
101
|
const windows = [];
|
|
124
102
|
let current = [];
|
package/dist/facts/handoff.js
CHANGED
|
@@ -4,6 +4,8 @@ export const HANDOFF_KEY = 'handoff';
|
|
|
4
4
|
const DAY_MS = 24 * 60 * 60 * 1000;
|
|
5
5
|
const HANDOFF_MAX_AGE_MS = 14 * DAY_MS;
|
|
6
6
|
const MANUAL_NOTES_SCANNED = 50;
|
|
7
|
+
const HANDOFF_MAX_LINES = 8;
|
|
8
|
+
const HANDOFF_LINE_CHARS = 220;
|
|
7
9
|
export async function newestHandoff(ctx, project, now = Date.now()) {
|
|
8
10
|
const notes = await ctx.store.list({
|
|
9
11
|
project,
|
|
@@ -16,10 +18,18 @@ export async function newestHandoff(ctx, project, now = Date.now()) {
|
|
|
16
18
|
now - obs.createdAt <= HANDOFF_MAX_AGE_MS;
|
|
17
19
|
return notes.find(current) ?? null;
|
|
18
20
|
}
|
|
21
|
+
function clipLine(line) {
|
|
22
|
+
return line.length > HANDOFF_LINE_CHARS
|
|
23
|
+
? `${line.slice(0, HANDOFF_LINE_CHARS - 1).trimEnd()}…`
|
|
24
|
+
: line;
|
|
25
|
+
}
|
|
19
26
|
export function handoffBodyLines(obs) {
|
|
20
|
-
|
|
27
|
+
const lines = obs.body
|
|
21
28
|
.split('\n')
|
|
22
29
|
.slice(1)
|
|
23
30
|
.map((line) => line.trimEnd())
|
|
24
31
|
.filter((line) => line.trim().length > 0);
|
|
32
|
+
const shown = lines.slice(0, HANDOFF_MAX_LINES).map(clipLine);
|
|
33
|
+
const hidden = lines.length - shown.length;
|
|
34
|
+
return hidden > 0 ? [...shown, `- ...${hidden} more line(s) in the full note`] : shown;
|
|
25
35
|
}
|
|
@@ -0,0 +1,4 @@
|
|
|
1
|
+
import type { RecallContext } from '../context.js';
|
|
2
|
+
import type { ExistingFact } from './ops.js';
|
|
3
|
+
export declare function existingFacts(ctx: RecallContext, project: string): Promise<ExistingFact[]>;
|
|
4
|
+
export declare function notedByUser(ctx: RecallContext, project: string): Promise<string[]>;
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
import { HANDOFF_TAG } from './handoff.js';
|
|
2
|
+
import { FACT_SESSION, factKey, factType, onePerKey, youScope } from './model.js';
|
|
3
|
+
import { MANUAL_SESSION } from './render.js';
|
|
4
|
+
const EXISTING_LIMIT = 80;
|
|
5
|
+
export async function existingFacts(ctx, project) {
|
|
6
|
+
const owners = [
|
|
7
|
+
[project, 'project'],
|
|
8
|
+
[youScope(), 'you'],
|
|
9
|
+
];
|
|
10
|
+
const facts = [];
|
|
11
|
+
for (const [owner, scope] of owners) {
|
|
12
|
+
const rows = await ctx.store.list({
|
|
13
|
+
project: owner,
|
|
14
|
+
sessionId: FACT_SESSION,
|
|
15
|
+
newest: true,
|
|
16
|
+
limit: EXISTING_LIMIT,
|
|
17
|
+
});
|
|
18
|
+
for (const obs of onePerKey(rows.filter((row) => row.status !== 'replaced'))) {
|
|
19
|
+
const key = factKey(obs);
|
|
20
|
+
const type = factType(obs);
|
|
21
|
+
if (obs.status === 'replaced' || !key || !type)
|
|
22
|
+
continue;
|
|
23
|
+
facts.push({ key, type, scope, text: obs.title });
|
|
24
|
+
}
|
|
25
|
+
}
|
|
26
|
+
return facts;
|
|
27
|
+
}
|
|
28
|
+
export async function notedByUser(ctx, project) {
|
|
29
|
+
const rows = await ctx.store.list({
|
|
30
|
+
project,
|
|
31
|
+
sessionId: MANUAL_SESSION,
|
|
32
|
+
newest: true,
|
|
33
|
+
limit: EXISTING_LIMIT,
|
|
34
|
+
});
|
|
35
|
+
return rows
|
|
36
|
+
.filter((row) => row.status !== 'replaced' && !row.tags.includes(HANDOFF_TAG))
|
|
37
|
+
.map((row) => row.title);
|
|
38
|
+
}
|
package/dist/facts/ops.d.ts
CHANGED
|
@@ -19,5 +19,5 @@ export interface RetireOp {
|
|
|
19
19
|
key: string;
|
|
20
20
|
}
|
|
21
21
|
export type FactOp = SetOp | RetireOp;
|
|
22
|
-
export declare function buildDistillPrompt(chat: string, existing: ExistingFact[]): string;
|
|
22
|
+
export declare function buildDistillPrompt(chat: string, existing: ExistingFact[], noted?: string[]): string;
|
|
23
23
|
export declare function parseOps(stdout: string): FactOp[];
|
package/dist/facts/ops.js
CHANGED
|
@@ -4,11 +4,12 @@ const KEY = /^[a-z0-9][a-z0-9-]{1,59}$/;
|
|
|
4
4
|
const TEXT_MAX = 200;
|
|
5
5
|
const WHY_MAX = 300;
|
|
6
6
|
const FILES_MAX = 5;
|
|
7
|
-
export function buildDistillPrompt(chat, existing) {
|
|
7
|
+
export function buildDistillPrompt(chat, existing, noted = []) {
|
|
8
8
|
return [
|
|
9
9
|
'You keep the long-term memory of a software project for a coding assistant. Read the',
|
|
10
10
|
'CHAT LOG of one past session and decide what is worth remembering in future sessions.',
|
|
11
|
-
'EXISTING FACTS are what is already remembered.',
|
|
11
|
+
'EXISTING FACTS are what is already remembered. NOTED BY THE USER are rules the user saved',
|
|
12
|
+
'by hand. They are remembered too, so never write a fact that repeats one of them.',
|
|
12
13
|
'',
|
|
13
14
|
'Write one JSON object per line, and nothing else:',
|
|
14
15
|
'{"op":"set","key":"short-kebab-key","type":"rule","scope":"project","text":"...","why":"...","files":["src/a.ts"]}',
|
|
@@ -33,6 +34,7 @@ export function buildDistillPrompt(chat, existing) {
|
|
|
33
34
|
...existing.map((fact) => `${fact.key} [${fact.type}, ${fact.scope}] ${fact.text}`),
|
|
34
35
|
'</existing-facts>',
|
|
35
36
|
'',
|
|
37
|
+
...(noted.length > 0 ? ['<noted-by-user>', ...noted, '</noted-by-user>', ''] : []),
|
|
36
38
|
'<chat-log>',
|
|
37
39
|
chat,
|
|
38
40
|
'</chat-log>',
|
package/dist/facts/start.js
CHANGED
|
@@ -3,6 +3,7 @@ import { FACT_SESSION, factType, onePerKey, youScope } from './model.js';
|
|
|
3
3
|
import { newestHandoff, handoffBodyLines } from './handoff.js';
|
|
4
4
|
import { MANUAL_SESSION, factLine, seenByClaude } from './render.js';
|
|
5
5
|
import { formatDay } from '../util/day.js';
|
|
6
|
+
import { toShortId } from '../util/shortid.js';
|
|
6
7
|
const ABOUT_YOU = 6;
|
|
7
8
|
const THIS_PROJECT = 10;
|
|
8
9
|
const TODOS = 4;
|
|
@@ -64,5 +65,8 @@ export async function startFacts(ctx, project, hidden = new Set()) {
|
|
|
64
65
|
return { block: lines.join('\n'), ids };
|
|
65
66
|
}
|
|
66
67
|
function handoffEntries(handoff) {
|
|
67
|
-
return handoffBodyLines(handoff).map((line, index) => [
|
|
68
|
+
return handoffBodyLines(handoff).map((line, index) => [
|
|
69
|
+
index === 0 ? `${line} (${toShortId(handoff.id)})` : line,
|
|
70
|
+
index === 0 ? handoff.id : null,
|
|
71
|
+
]);
|
|
68
72
|
}
|
package/docs/setup-guide.md
CHANGED
|
@@ -1,36 +1,13 @@
|
|
|
1
|
-
# Setup guide
|
|
1
|
+
# Setup guide
|
|
2
2
|
|
|
3
|
-
|
|
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
|
|
3
|
+
Get the best results from claude-db in five steps. For how it works inside, see
|
|
10
4
|
[how-it-works.md](./how-it-works.md).
|
|
11
5
|
|
|
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
6
|
## 1. Requirements
|
|
26
7
|
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
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.
|
|
8
|
+
- Node 22.16 or newer (`node -v`)
|
|
9
|
+
- A git repository
|
|
10
|
+
- Claude Code, logged in
|
|
34
11
|
|
|
35
12
|
## 2. Install
|
|
36
13
|
|
|
@@ -40,309 +17,80 @@ cd your-project
|
|
|
40
17
|
claude-db install --project
|
|
41
18
|
```
|
|
42
19
|
|
|
43
|
-
|
|
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.
|
|
20
|
+
Then restart Claude Code. Hooks and the MCP server load only when Claude Code starts.
|
|
57
21
|
|
|
58
|
-
|
|
22
|
+
- Use `claude-db install` instead to switch it on for every project on this machine.
|
|
23
|
+
- Keep `.mcp.json` and `CLAUDE.local.md` out of git. They hold personal paths and rules.
|
|
59
24
|
|
|
60
|
-
|
|
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 three
|
|
71
|
-
skills: `/cdb-scan`, `/catchup` and `/handoff`. If you already have a skill with the same name, claude-db keeps
|
|
72
|
-
yours and says so.
|
|
73
|
-
|
|
74
|
-
### Keep personal files out of git
|
|
75
|
-
|
|
76
|
-
`.mcp.json` holds an absolute path on your machine, so committing it breaks the project for everyone
|
|
77
|
-
else. `CLAUDE.local.md` and `.claude/settings.local.json` are meant to be personal too. Make sure all
|
|
78
|
-
three are ignored:
|
|
79
|
-
|
|
80
|
-
```bash
|
|
81
|
-
printf '\n.mcp.json\nCLAUDE.local.md\n.claude/settings.local.json\n' >> .gitignore
|
|
82
|
-
```
|
|
83
|
-
|
|
84
|
-
The installer only reminds you about `.mcp.json`, and only when no `.gitignore` lists it.
|
|
85
|
-
|
|
86
|
-
### Restart Claude Code
|
|
87
|
-
|
|
88
|
-
The MCP server and the hooks are loaded when Claude Code starts. A session that was already open does
|
|
89
|
-
not have them.
|
|
90
|
-
|
|
91
|
-
## 3. Check that it works
|
|
92
|
-
|
|
93
|
-
```bash
|
|
94
|
-
claude-db status
|
|
95
|
-
```
|
|
96
|
-
|
|
97
|
-
Right after install you should see this, with your own paths:
|
|
98
|
-
|
|
99
|
-
```text
|
|
100
|
-
project : ~/shop
|
|
101
|
-
database : ~/.claude-memory/memory.db
|
|
102
|
-
hooks : this project
|
|
103
|
-
mcp : registered (~/shop/.mcp.json)
|
|
104
|
-
sessions : 0 recorded for this project
|
|
105
|
-
worked : never
|
|
106
|
-
recorded : never
|
|
107
|
-
facts : 0 for this project, 0 about you
|
|
108
|
-
waiting : 0 chat(s) not yet turned into facts
|
|
109
|
-
pick : on (haiku), 0 of 150 picks used today
|
|
110
|
-
```
|
|
111
|
-
|
|
112
|
-
"Nothing recorded yet" is normal here. Memory is written as you work, only for turns that changed
|
|
113
|
-
something, so a chat of questions leaves nothing behind. After your first real session, `sessions`
|
|
114
|
-
and `recorded` fill in.
|
|
25
|
+
## 3. Check it works
|
|
115
26
|
|
|
116
27
|
```bash
|
|
117
28
|
claude-db doctor
|
|
29
|
+
claude-db status
|
|
118
30
|
```
|
|
119
31
|
|
|
120
|
-
`doctor`
|
|
121
|
-
|
|
122
|
-
test memory, searches for it, reads it back and deletes it, and tells you which step failed if any.
|
|
32
|
+
`doctor` should end with `wiring : ok`. After your first real session, `status` shows what was
|
|
33
|
+
recorded. Nothing is saved for a chat that only asked questions, and that is normal.
|
|
123
34
|
|
|
124
35
|
## 4. Give it a head start
|
|
125
36
|
|
|
126
|
-
A fresh install has nothing to recall.
|
|
127
|
-
|
|
128
|
-
| Step | Command | What it does | Cost |
|
|
129
|
-
| ------------------------------------ | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
|
|
130
|
-
| 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 |
|
|
131
|
-
| 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 |
|
|
132
|
-
| Read the git history | `claude-db seed --from-git` | Turns your commit history into memory so search has something to match | none |
|
|
133
|
-
| 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 |
|
|
134
|
-
| Ask where you stopped | `/catchup` | Prints done, open and next from the last chat, the recorded to-dos, the last handoff and git. Writes nothing. The raw facts are also in `claude-db catchup` | a normal chat turn |
|
|
135
|
-
| Hand work to the next chat | `/handoff` | Writes a short note (done, open, next), saves it as the project's one current handoff and prints it. The next chat sees it at the start for 14 days | a normal chat turn |
|
|
136
|
-
| 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 |
|
|
37
|
+
A fresh install has nothing to recall. Run these once:
|
|
137
38
|
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
39
|
+
| Command | What you get |
|
|
40
|
+
| --------------------------- | ---------------------------------------------------------------- |
|
|
41
|
+
| `claude-db flush` | Your past chats for this project, loaded into memory |
|
|
42
|
+
| `claude-db scan` | A map of your code, so Claude can find symbols and their callers |
|
|
43
|
+
| `claude-db seed --from-git` | Your commit history, loaded into memory |
|
|
143
44
|
|
|
144
|
-
|
|
45
|
+
Old chats are also turned into short facts in the background, newest first, within a daily limit.
|
|
145
46
|
|
|
146
|
-
|
|
147
|
-
[memory-improvements.md](https://github.com/Avijit07x/claude-db/blob/main/docs/memory-improvements.md).
|
|
47
|
+
## 5. Work in ways that help
|
|
148
48
|
|
|
149
|
-
- **Be specific.**
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
- **
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
useful. A turn in which Claude uses no tools never shows a pick.
|
|
156
|
-
- **Say why.** "We chose a websocket because polling hammered the API" becomes a decision with its
|
|
157
|
-
reason. "That approach failed because..." becomes a dead end. These are what a later chat needs.
|
|
158
|
-
- **State a rule once, plainly.** Tell Claude to remember it, or run `claude-db remember`.
|
|
159
|
-
- **Commit finished work.** Work that changed files stays listed as "Not committed" in `status` and at
|
|
160
|
-
the start of a chat until those files are committed.
|
|
161
|
-
- **Wrap anything private in `<private>...</private>`.** It is removed before the turn is saved.
|
|
162
|
-
- **Use `/compact` freely.** When a chat is compacted, its own decisions and open work are put back.
|
|
163
|
-
- **Keep `CLAUDE.md` for a stable overview of the project.** claude-db stores what happened, which is
|
|
164
|
-
a different job.
|
|
165
|
-
- **Look at what it holds.** `claude-db search <words>`, `claude-db stats`, and `claude-db view` for a
|
|
166
|
-
page in the browser.
|
|
49
|
+
- **Be specific.** "Make the order feed reconnect with backoff" finds memory. "ok" and "continue" do not.
|
|
50
|
+
- **Say why.** "We chose a websocket because polling hammered the API" is kept as a decision with its reason.
|
|
51
|
+
- **State a rule once.** Tell Claude to remember it, or run `claude-db remember "always use pnpm"`.
|
|
52
|
+
- **Commit finished work.** Uncommitted work stays listed as open.
|
|
53
|
+
- **Wrap private text in `<private>...</private>`.** It is removed before saving.
|
|
54
|
+
- **Use `/catchup` when you return and `/handoff` when you stop.**
|
|
167
55
|
|
|
168
|
-
##
|
|
56
|
+
## Cost and privacy
|
|
169
57
|
|
|
170
|
-
|
|
171
|
-
It is created the first time a command changes a setting, such as `claude-db pick off`,
|
|
172
|
-
`claude-db distill off` or `claude-db use`. Edit it by hand for the rest, and list only the keys you
|
|
173
|
-
want to change.
|
|
58
|
+
Two small background features call Claude Haiku through your own login:
|
|
174
59
|
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
| `pick.enabled` | `true` | Let Haiku pick the memory shown with a prompt | you want no Claude usage for this (`claude-db pick off`) |
|
|
178
|
-
| `pick.dailyLimit` | `150` | Most picks a day. After that, only strong word matches are shown | you work a lot in one day |
|
|
179
|
-
| `pick.model` | `haiku` | `haiku`, `sonnet` or `opus` | almost never; Haiku was the one measured |
|
|
180
|
-
| `distill.enabled` | `true` | Turn finished chats into facts | you want no Claude usage for this (`claude-db distill off`) |
|
|
181
|
-
| `distill.dailyLimit` | `30` | Most fact-making calls a day | you have many old chats to catch up on |
|
|
182
|
-
| `distill.backfillDays` | `90` | How far back older chats are turned into facts | you want a shorter or longer reach |
|
|
183
|
-
| `inject.perPrompt` | `true` | Show related memory with prompts at all | you want memory only at the start of a chat |
|
|
184
|
-
| `inject.minOverlap` | `2` | Meaningful words a memory must share with the prompt | almost never; 2 was the best floor measured |
|
|
185
|
-
| `inject.promptResults` | `2` | Most memories shown with one prompt | you want more or fewer lines |
|
|
186
|
-
| `project.remote` | `origin` | The git remote that names a project | your main remote is not `origin` (a fork's `upstream`) |
|
|
187
|
-
| `updates` | `notify` | `notify`, `auto` or `off` | you want updates installed for you, or never checked |
|
|
188
|
-
| `embeddings.provider` | `auto` | `auto`, `local`, `builtin` or `none` | you install the optional embedding model, or want none |
|
|
60
|
+
- Picking the best memory for a prompt (up to 150 a day).
|
|
61
|
+
- Turning finished chats into facts (up to 30 a day).
|
|
189
62
|
|
|
190
|
-
|
|
63
|
+
Turn either off with `claude-db pick off` and `claude-db distill off`. Memory is still recorded and
|
|
64
|
+
searched without them, but fewer prompts get relevant memory. Secrets such as API keys and `.env`
|
|
65
|
+
files are never stored or sent.
|
|
191
66
|
|
|
192
|
-
|
|
67
|
+
## Teams and several machines
|
|
193
68
|
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
```json
|
|
197
|
-
{
|
|
198
|
-
"pick": { "enabled": false },
|
|
199
|
-
"distill": { "enabled": false }
|
|
200
|
-
}
|
|
201
|
-
```
|
|
202
|
-
|
|
203
|
-
The cost is quality. Without Haiku, a prompt only gets memory when the closest one shares four
|
|
204
|
-
meaningful words with it. In testing that showed memory on about 12% of prompts, and it was useful
|
|
205
|
-
43% of the time, against about 6 to 7 in 10 with Haiku. No new facts are made, so the start of a
|
|
206
|
-
chat shows the facts it already has, or recent session summaries if there are none.
|
|
207
|
-
|
|
208
|
-
**Heavy use.** Raise the limits if you hit them. `claude-db pick` and `claude-db distill` show how
|
|
209
|
-
much of today's limit is used:
|
|
210
|
-
|
|
211
|
-
```json
|
|
212
|
-
{
|
|
213
|
-
"pick": { "dailyLimit": 400 },
|
|
214
|
-
"distill": { "dailyLimit": 60 }
|
|
215
|
-
}
|
|
216
|
-
```
|
|
217
|
-
|
|
218
|
-
### Better embeddings are optional
|
|
219
|
-
|
|
220
|
-
The built-in embedder works without installing anything. For semantic matching in `search`:
|
|
221
|
-
|
|
222
|
-
```bash
|
|
223
|
-
npm install -g @xenova/transformers
|
|
224
|
-
claude-db reembed
|
|
225
|
-
```
|
|
226
|
-
|
|
227
|
-
This is a large download (about 200 MB of libraries plus a model). It is not needed for picking, and
|
|
228
|
-
its effect on the memory shown with prompts was not measured.
|
|
229
|
-
|
|
230
|
-
## 7. Cost and privacy
|
|
231
|
-
|
|
232
|
-
Nothing leaves your machine except the things below, and each can be turned off.
|
|
233
|
-
|
|
234
|
-
| What | When | What is sent | Cost | Limit | Turn it off |
|
|
235
|
-
| ------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ---------- | ----------------------- |
|
|
236
|
-
| 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` |
|
|
237
|
-
| 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` |
|
|
238
|
-
| Update check | Once a day | A request to the npm registry | none | once a day | `"updates": "off"` |
|
|
239
|
-
| Your database | Only if you set a remote one | Your memory | depends on the host | none | `claude-db use <path>` |
|
|
240
|
-
|
|
241
|
-
Both Haiku features go through your own Claude Code login, so they count against your plan like any
|
|
242
|
-
other use. Haiku is the lightest model, and a pick is small next to an ordinary chat turn. A failed
|
|
243
|
-
call pauses that feature for an hour, then six hours, then a day if calls keep failing, while recording
|
|
244
|
-
carries on. `claude-db status` shows the reason.
|
|
245
|
-
|
|
246
|
-
What is never stored: `.env` files, anything under `secrets/`, `node_modules` and `.git/`. Text in
|
|
247
|
-
`<private>...</private>` is stripped. API keys, tokens, private keys, connection-string passwords and
|
|
248
|
-
`NAME=value` secrets are redacted before anything is saved or sent. `claude-db redact` re-applies the
|
|
249
|
-
current rules to memory saved earlier; it also runs once on its own after an update.
|
|
250
|
-
|
|
251
|
-
One limit to know about: a secret you paste into a chat also stays in Claude Code's own chat file,
|
|
252
|
-
which claude-db does not edit. If you paste a real secret, rotate it.
|
|
253
|
-
|
|
254
|
-
## 8. Teams and several machines
|
|
255
|
-
|
|
256
|
-
SQLite is the default and needs no setup. To share memory, point claude-db at a database everyone can
|
|
257
|
-
reach:
|
|
69
|
+
By default memory is one SQLite file on your machine. To share it, point everyone at one database:
|
|
258
70
|
|
|
259
71
|
```bash
|
|
260
72
|
npm install -g pg
|
|
261
73
|
claude-db use "postgres://user:pass@host:5432/memory"
|
|
262
74
|
```
|
|
263
75
|
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
address, and warns if the database already holds tables that are not claude-db's. Give it a database
|
|
267
|
-
of its own.
|
|
268
|
-
|
|
269
|
-
- **Projects are matched by git remote.** A repository with an `origin` remote is one project wherever it
|
|
270
|
-
is cloned, so `github.com/acme/shop` on your laptop and on your Mac share memory. `ssh` and `https`
|
|
271
|
-
addresses of the same repository match, and any token in the address is never stored. A folder with no
|
|
272
|
-
remote is matched by its path, as before. A fork has its own remote, so it is its own project. Set
|
|
273
|
-
`project.remote` to use a remote other than `origin`. Memory saved before this, under a folder path, is
|
|
274
|
-
still found and is not moved. `claude-db merge <old-path> --yes` still works for a folder with no remote.
|
|
275
|
-
- **Personal rules stay personal.** A rule about how you like to work is filed under your git email,
|
|
276
|
-
so it follows you into every project and never reaches a teammate on a shared database. Set
|
|
277
|
-
`git config user.email` so it is filed under the right name. Everything else belongs to the
|
|
278
|
-
project and is shared.
|
|
279
|
-
- **Two databases, one memory.** `claude-db sync <url>` merges two databases in both directions, so a
|
|
280
|
-
laptop and a desktop can each work offline and reconcile later. `claude-db export` and
|
|
281
|
-
`claude-db import` do the same with a file.
|
|
282
|
-
- **Use a restricted account.** Connection strings are redacted whenever claude-db prints them, but
|
|
283
|
-
the account should only be able to reach its own database.
|
|
284
|
-
|
|
285
|
-
## 9. Keep it healthy
|
|
76
|
+
For MongoDB, install `mongodb` and use a `mongodb+srv://` address. Clones of one repository share
|
|
77
|
+
memory by git remote, so every machine must run 0.11.0 or newer.
|
|
286
78
|
|
|
287
|
-
|
|
288
|
-
| ------------------------- | ---------------------------------- | --------------------------------------------------------------------- |
|
|
289
|
-
| Now and then | `claude-db status` | Wired up, last recorded, open work, how many picks used today |
|
|
290
|
-
| Now and then | `claude-db stats` | What memory is made of, by kind and by area |
|
|
291
|
-
| After a big refactor | `claude-db scan` | Refreshes the code graph (it also refreshes at each session start) |
|
|
292
|
-
| When memory is stale | `claude-db prune --older-than 180` | A dry run that counts what would go; add `--yes` to delete |
|
|
293
|
-
| When something is wrong | `claude-db forget <id>` | Deletes a memory that turned out to be wrong, so it stops coming back |
|
|
294
|
-
| After moving a repository | `claude-db merge <old-path> --yes` | Brings memory filed under the old path across |
|
|
295
|
-
|
|
296
|
-
`claude-db uninstall --project` removes the hooks, the MCP entry and the instructions, and leaves your
|
|
297
|
-
memory untouched. Only `forget`, `prune` and `reset` delete memory, and the last two do nothing without
|
|
298
|
-
`--yes`.
|
|
299
|
-
|
|
300
|
-
## 10. Upgrading
|
|
79
|
+
## Upgrading
|
|
301
80
|
|
|
302
81
|
```bash
|
|
303
82
|
npm install -g claude-db
|
|
304
83
|
```
|
|
305
84
|
|
|
306
|
-
|
|
307
|
-
one-time jobs may run in the background, and none of them blocks a chat:
|
|
308
|
-
|
|
309
|
-
- repairing memory that an older version saved badly (`claude-db flush --repair`),
|
|
310
|
-
- re-applying secret redaction to everything already saved (`claude-db redact`),
|
|
311
|
-
- turning older chats into facts, which carries on over the next sessions within the daily limit.
|
|
312
|
-
|
|
313
|
-
Hooks that an earlier install registered are brought up to date automatically at session start, so a
|
|
314
|
-
new hook arrives without running `install` again. The first chat after you get facts says so once, and
|
|
315
|
-
how to switch that off with `claude-db distill off`.
|
|
316
|
-
|
|
317
|
-
## 11. When something is off
|
|
318
|
-
|
|
319
|
-
| What you see | Check |
|
|
320
|
-
| ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
321
|
-
| 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 |
|
|
322
|
-
| 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 |
|
|
323
|
-
| 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 |
|
|
324
|
-
| `doctor` says `registered 2x` | Run `claude-db install` again. It replaces its own entries |
|
|
325
|
-
| Install stops with a Node version message | Upgrade to Node 22.16 or newer |
|
|
326
|
-
| `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 |
|
|
327
|
-
| A moved repository looks empty | A repository with a remote keeps its memory. With no remote, run `claude-db merge <old-path> --yes` |
|
|
328
|
-
| Search got worse after adding the embedding model | Run `claude-db reembed` |
|
|
329
|
-
|
|
330
|
-
The [troubleshooting page](https://claude-db.vercel.app/docs/troubleshooting) covers the rest.
|
|
85
|
+
Then restart Claude Code. Memory is kept.
|
|
331
86
|
|
|
332
|
-
##
|
|
87
|
+
## When something is off
|
|
333
88
|
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
| `~/.claude-memory/pick/` | Picks in flight and today's pick count |
|
|
340
|
-
| `~/.claude-memory/distill/` | Today's fact-making count |
|
|
341
|
-
| `~/.claude-memory/reingest/`, `redact/` | Marks that a one-time job has finished, per project or database |
|
|
342
|
-
| `.claude/settings.local.json` | The hooks, for a project install |
|
|
343
|
-
| `.mcp.json` | The MCP server, for a project install |
|
|
344
|
-
| `CLAUDE.local.md` | The standing instruction to search memory |
|
|
345
|
-
| `.claude/skills/cdb-scan/` | The `/cdb-scan` skill |
|
|
346
|
-
| `.claude/skills/catchup/`, `handoff/` | The `/catchup` and `/handoff` skills |
|
|
89
|
+
- **Nothing recorded:** restart Claude Code, and check that `install` ran in this repository.
|
|
90
|
+
- **Memory rarely shows up:** run the head start steps, and run `claude-db pick` to see if picking
|
|
91
|
+
is off or at its limit.
|
|
92
|
+
- **`doctor` shows `reachable: no`:** for Postgres or MongoDB, install the driver (`pg` or `mongodb`).
|
|
93
|
+
- **Remove it:** `claude-db uninstall --project`. Your memory is kept.
|
|
347
94
|
|
|
348
|
-
|
|
95
|
+
Commands are in the [README](../README.md) and `claude-db --help`. Every setting is listed in
|
|
96
|
+
[architecture.md](./architecture.md).
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "claude-db",
|
|
3
|
-
"version": "0.11.
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "0.11.1",
|
|
4
|
+
"description": "Free, open-source memory for Claude Code. Remembers why decisions were made and maps your code. Your own database (SQLite, Postgres or MongoDB), no cloud, no subscription.",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"type": "module",
|
|
7
7
|
"bin": {
|
package/skills/catchup/SKILL.md
CHANGED
|
@@ -18,6 +18,8 @@ with nothing in it is left out.
|
|
|
18
18
|
- `Last chat` is the newest recorded chat, with a few lines of the work done in it.
|
|
19
19
|
- `Still to do` are to-dos found in earlier chats.
|
|
20
20
|
- `Not committed yet` is recorded work that no commit has covered.
|
|
21
|
+
- `Decisions and dead ends` are what was chosen or ruled out, with the reason.
|
|
22
|
+
- `Branch` says which branch you are on and how many files are uncommitted.
|
|
21
23
|
- `Git status` and `Recent commits` are the live state of the repository.
|
|
22
24
|
|
|
23
25
|
If the output is `Nothing recorded for this project yet.`, say exactly that and stop.
|
package/skills/handoff/SKILL.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: handoff
|
|
3
|
-
description: Write a short handoff note for the next chat or a teammate, with what is done, what is open and what
|
|
3
|
+
description: Write a short handoff note for the next chat or a teammate, with what is done, what is open, what comes next and what was rejected and why. Saves it to project memory so the next chat sees it at the start, and prints it so it can be pasted into a message or a pull request. Use when the user ends a piece of work, switches tasks, or hands the project to someone.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Write a handoff note
|
|
@@ -14,27 +14,42 @@ claude-db catchup
|
|
|
14
14
|
```
|
|
15
15
|
|
|
16
16
|
Combine that with what happened in this chat. The chat is the best source for what was done and what is
|
|
17
|
-
still open. The output fills gaps and checks dates.
|
|
17
|
+
still open. The output fills gaps and checks dates. If it shows a `Last handoff`, that is the note you
|
|
18
|
+
will carry forward in step 2.
|
|
18
19
|
|
|
19
20
|
## 2. Write the note
|
|
20
21
|
|
|
21
|
-
|
|
22
|
+
The first line is the title and has today's date. Get it with `date '+%b %-d'`. Then write at most 8 lines,
|
|
23
|
+
each under about 200 characters. The next chat reads this note at its start, so every line costs context.
|
|
22
24
|
|
|
23
25
|
```
|
|
24
|
-
Handoff, Oct
|
|
26
|
+
Handoff, Oct 7:
|
|
25
27
|
- Done: timers, queue, mail family.
|
|
26
28
|
- Open: PR #18 not merged.
|
|
27
29
|
- Next: ask which retries to change on the worker queue.
|
|
30
|
+
- Decided: retries stay at 3, because the queue already backs off.
|
|
31
|
+
- Rejected: a second worker pool, because it doubled the mail cost.
|
|
32
|
+
- Watch out: tests read dist/, so run the build first.
|
|
33
|
+
- State: branch v0.12, 4 files uncommitted, last commit 1db3638.
|
|
28
34
|
```
|
|
29
35
|
|
|
30
|
-
|
|
36
|
+
Lines:
|
|
31
37
|
|
|
32
|
-
-
|
|
38
|
+
- `Done`, `Open` and `Next` are always there. One line each.
|
|
39
|
+
- `Decided`, `Rejected`, `Watch out` and `State` only when there is something real to say. Never pad.
|
|
40
|
+
- `Rejected` and `Decided` give the reason after "because". A rejected idea with no reason is not worth a line.
|
|
41
|
+
- `State` comes from the `catchup` output, not from memory: the `Branch` line and the newest of the
|
|
42
|
+
`Recent commits`. Add a pull request number only if this chat mentioned one.
|
|
43
|
+
- `Decided` and `Rejected` start from `Decisions and dead ends` in the output, plus this chat.
|
|
33
44
|
- Name real things: a file, a pull request number, a command, a decision. Do not write `various changes`.
|
|
34
45
|
- Use only what this chat or the output showed. Mark anything you are unsure of with `(guess)`.
|
|
35
46
|
- If there is no clear next step, write `- Next: no clear next step yet.` Do not invent one.
|
|
36
47
|
- Leave out secrets, tokens, passwords and personal data.
|
|
37
48
|
|
|
49
|
+
Carry forward. Keep a line from the previous handoff when it is still true and still matters, and add the
|
|
50
|
+
date to it, for example `(Oct 5)`. Drop what is finished or wrong. If the note is over 8 lines, shorten lines
|
|
51
|
+
or drop the oldest finished ones. Never drop a `Rejected` line that is still true.
|
|
52
|
+
|
|
38
53
|
## 3. Save it
|
|
39
54
|
|
|
40
55
|
Call the `remember` memory tool once, with these exact values:
|
|
@@ -45,7 +60,8 @@ Call the `remember` memory tool once, with these exact values:
|
|
|
45
60
|
- `tags`: `["handoff"]`
|
|
46
61
|
|
|
47
62
|
The key makes a new handoff replace the old one for this project, so there is one current note. The next
|
|
48
|
-
chat sees it at the start under `Last handoff`. It is shown for 14 days.
|
|
63
|
+
chat sees it at the start under `Last handoff`. It is shown for 14 days. Only the first 8 lines are shown,
|
|
64
|
+
each cut at about 220 characters.
|
|
49
65
|
|
|
50
66
|
## 4. Print it
|
|
51
67
|
|