claude-db 0.10.3 → 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 +66 -0
- package/README.md +41 -78
- package/dist/catchup/gather.d.ts +18 -0
- package/dist/catchup/gather.js +46 -0
- package/dist/catchup/git-state.d.ts +9 -0
- package/dist/catchup/git-state.js +35 -0
- package/dist/catchup/render.d.ts +3 -0
- package/dist/catchup/render.js +49 -0
- package/dist/cli/backfill-output.d.ts +13 -0
- package/dist/cli/backfill-output.js +78 -0
- package/dist/cli/commands/catchup.d.ts +1 -0
- package/dist/cli/commands/catchup.js +14 -0
- package/dist/cli/commands/distill.js +13 -2
- package/dist/cli/commands/doctor.d.ts +2 -0
- package/dist/cli/commands/doctor.js +42 -3
- package/dist/cli/commands/insight.js +2 -1
- package/dist/cli/commands/setup.js +29 -9
- package/dist/cli/files.d.ts +2 -0
- package/dist/cli/files.js +15 -1
- package/dist/cli/index.js +9 -0
- package/dist/cli/install.d.ts +6 -1
- package/dist/cli/install.js +11 -20
- package/dist/cli/paths.d.ts +1 -1
- package/dist/cli/paths.js +2 -2
- package/dist/cli/refresh.js +4 -12
- package/dist/cli/skills.d.ts +17 -0
- package/dist/cli/skills.js +70 -0
- package/dist/cli/usage.js +2 -0
- package/dist/config/schema.d.ts +3 -0
- package/dist/config/schema.js +8 -0
- package/dist/context.js +5 -2
- package/dist/facts/distill.d.ts +16 -3
- package/dist/facts/distill.js +22 -31
- package/dist/facts/handoff.d.ts +6 -0
- package/dist/facts/handoff.js +35 -0
- package/dist/facts/health.d.ts +3 -0
- package/dist/facts/health.js +10 -0
- package/dist/facts/known.d.ts +4 -0
- package/dist/facts/known.js +38 -0
- package/dist/facts/model.d.ts +1 -0
- package/dist/facts/model.js +12 -0
- package/dist/facts/ops.d.ts +1 -1
- package/dist/facts/ops.js +4 -2
- package/dist/facts/start.js +20 -5
- package/dist/store/adapter.d.ts +4 -2
- package/dist/store/adapter.js +1 -1
- package/dist/store/mongo/docs.d.ts +6 -0
- package/dist/store/mongo/filters.d.ts +2 -1
- package/dist/store/mongo/filters.js +9 -2
- package/dist/store/mongo/index.d.ts +5 -2
- package/dist/store/mongo/index.js +13 -2
- package/dist/store/mongo/observations.js +9 -5
- package/dist/store/mongo/project-links.d.ts +4 -0
- package/dist/store/mongo/project-links.js +13 -0
- package/dist/store/mongo/search.js +3 -0
- package/dist/store/mongo/sessions.d.ts +2 -2
- package/dist/store/mongo/sessions.js +5 -1
- package/dist/store/mongo/vectorSearch.js +3 -0
- package/dist/store/postgres/filters.d.ts +2 -1
- package/dist/store/postgres/filters.js +11 -4
- package/dist/store/postgres/index.d.ts +4 -2
- package/dist/store/postgres/index.js +7 -0
- package/dist/store/postgres/observations.js +15 -10
- package/dist/store/postgres/project-links.d.ts +3 -0
- package/dist/store/postgres/project-links.js +15 -0
- package/dist/store/postgres/schema.d.ts +2 -2
- package/dist/store/postgres/schema.js +9 -1
- package/dist/store/postgres/search.js +3 -0
- package/dist/store/postgres/sessions.d.ts +2 -2
- package/dist/store/postgres/sessions.js +9 -2
- package/dist/store/postgres/vectorSearch.js +3 -0
- package/dist/store/project-resolver.d.ts +16 -0
- package/dist/store/project-resolver.js +49 -0
- package/dist/store/project-scope.d.ts +5 -0
- package/dist/store/project-scope.js +16 -0
- package/dist/store/scoped-store.d.ts +3 -0
- package/dist/store/scoped-store.js +49 -0
- package/dist/store/sqlite/filters.d.ts +3 -2
- package/dist/store/sqlite/filters.js +23 -9
- package/dist/store/sqlite/index.d.ts +4 -2
- package/dist/store/sqlite/index.js +7 -0
- package/dist/store/sqlite/observations.js +13 -7
- package/dist/store/sqlite/project-links.d.ts +3 -0
- package/dist/store/sqlite/project-links.js +15 -0
- package/dist/store/sqlite/schema.sql +9 -0
- package/dist/store/sqlite/search.js +5 -0
- package/dist/store/sqlite/sessions.d.ts +2 -2
- package/dist/store/sqlite/sessions.js +8 -2
- package/dist/types.d.ts +4 -3
- package/dist/util/claude-binary.d.ts +15 -1
- package/dist/util/claude-binary.js +39 -7
- package/dist/util/project-key.d.ts +7 -0
- package/dist/util/project-key.js +23 -0
- package/dist/util/remote-key.d.ts +3 -0
- package/dist/util/remote-key.js +50 -0
- package/docs/setup-guide.md +47 -291
- package/package.json +2 -2
- package/skills/catchup/SKILL.md +46 -0
- package/skills/handoff/SKILL.md +78 -0
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
const REMOTE_NAME = /^[A-Za-z0-9._-]+$/;
|
|
2
|
+
const SCHEME_URL = /^([a-z][a-z0-9+.-]*):\/\/(.+)$/i;
|
|
3
|
+
const SCP_URL = /^(?:[^@/\s]+@)?([^:/\s]+):(?!\/\/)(.+)$/;
|
|
4
|
+
const WINDOWS_PATH = /^[a-z]:[\\/]/i;
|
|
5
|
+
const NETWORK_SCHEMES = new Set(['http', 'https', 'ssh', 'git', 'git+ssh', 'ssh+git']);
|
|
6
|
+
export const DEFAULT_REMOTE = 'origin';
|
|
7
|
+
export function isRemoteName(name) {
|
|
8
|
+
return REMOTE_NAME.test(name);
|
|
9
|
+
}
|
|
10
|
+
function splitAuthority(rest) {
|
|
11
|
+
const slash = rest.indexOf('/');
|
|
12
|
+
return slash === -1
|
|
13
|
+
? { authority: rest, path: '' }
|
|
14
|
+
: { authority: rest.slice(0, slash), path: rest.slice(slash + 1) };
|
|
15
|
+
}
|
|
16
|
+
function hostOf(authority) {
|
|
17
|
+
const withoutUser = authority.slice(authority.lastIndexOf('@') + 1);
|
|
18
|
+
return withoutUser.replace(/:\d*$/, '').toLowerCase();
|
|
19
|
+
}
|
|
20
|
+
function cleanPath(path) {
|
|
21
|
+
return path
|
|
22
|
+
.replace(/[?#].*$/, '')
|
|
23
|
+
.replace(/\/+$/, '')
|
|
24
|
+
.replace(/\.git$/i, '')
|
|
25
|
+
.replace(/\/+$/, '')
|
|
26
|
+
.toLowerCase();
|
|
27
|
+
}
|
|
28
|
+
function join(host, path) {
|
|
29
|
+
const segments = path.split('/').filter((part) => part.length > 0);
|
|
30
|
+
if (host.length === 0 || segments.length < 2 || segments.includes('..'))
|
|
31
|
+
return null;
|
|
32
|
+
return `${host}/${segments.join('/')}`;
|
|
33
|
+
}
|
|
34
|
+
export function normalizeRemote(url) {
|
|
35
|
+
const text = url.trim();
|
|
36
|
+
if (text.length === 0 || WINDOWS_PATH.test(text))
|
|
37
|
+
return null;
|
|
38
|
+
const scheme = SCHEME_URL.exec(text);
|
|
39
|
+
if (scheme) {
|
|
40
|
+
const [, name = '', rest = ''] = scheme;
|
|
41
|
+
if (!NETWORK_SCHEMES.has(name.toLowerCase()))
|
|
42
|
+
return null;
|
|
43
|
+
const { authority, path } = splitAuthority(rest);
|
|
44
|
+
return join(hostOf(authority), cleanPath(path));
|
|
45
|
+
}
|
|
46
|
+
const scp = SCP_URL.exec(text);
|
|
47
|
+
if (scp)
|
|
48
|
+
return join((scp[1] ?? '').toLowerCase(), cleanPath(scp[2] ?? ''));
|
|
49
|
+
return null;
|
|
50
|
+
}
|
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,301 +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 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.
|
|
25
|
+
## 3. Check it works
|
|
114
26
|
|
|
115
27
|
```bash
|
|
116
28
|
claude-db doctor
|
|
29
|
+
claude-db status
|
|
117
30
|
```
|
|
118
31
|
|
|
119
|
-
`doctor`
|
|
120
|
-
|
|
121
|
-
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.
|
|
122
34
|
|
|
123
35
|
## 4. Give it a head start
|
|
124
36
|
|
|
125
|
-
A fresh install has nothing to recall.
|
|
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 |
|
|
37
|
+
A fresh install has nothing to recall. Run these once:
|
|
134
38
|
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
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 |
|
|
140
44
|
|
|
141
|
-
|
|
45
|
+
Old chats are also turned into short facts in the background, newest first, within a daily limit.
|
|
142
46
|
|
|
143
|
-
|
|
144
|
-
[memory-improvements.md](https://github.com/Avijit07x/claude-db/blob/main/docs/memory-improvements.md).
|
|
47
|
+
## 5. Work in ways that help
|
|
145
48
|
|
|
146
|
-
- **Be specific.**
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
- **
|
|
150
|
-
|
|
151
|
-
|
|
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.
|
|
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.**
|
|
164
55
|
|
|
165
|
-
##
|
|
56
|
+
## Cost and privacy
|
|
166
57
|
|
|
167
|
-
|
|
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.
|
|
58
|
+
Two small background features call Claude Haiku through your own login:
|
|
171
59
|
|
|
172
|
-
|
|
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 |
|
|
60
|
+
- Picking the best memory for a prompt (up to 150 a day).
|
|
61
|
+
- Turning finished chats into facts (up to 30 a day).
|
|
185
62
|
|
|
186
|
-
|
|
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.
|
|
187
66
|
|
|
188
|
-
|
|
67
|
+
## Teams and several machines
|
|
189
68
|
|
|
190
|
-
|
|
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, then six hours, then a day if calls keep failing, while recording
|
|
240
|
-
carries on. `claude-db status` shows the reason.
|
|
241
|
-
|
|
242
|
-
What is never stored: `.env` files, anything under `secrets/`, `node_modules` and `.git/`. Text in
|
|
243
|
-
`<private>...</private>` is stripped. API keys, tokens, private keys, connection-string passwords and
|
|
244
|
-
`NAME=value` secrets are redacted before anything is saved or sent. `claude-db redact` re-applies the
|
|
245
|
-
current rules to memory saved earlier; it also runs once on its own after an update.
|
|
246
|
-
|
|
247
|
-
One limit to know about: a secret you paste into a chat also stays in Claude Code's own chat file,
|
|
248
|
-
which claude-db does not edit. If you paste a real secret, rotate it.
|
|
249
|
-
|
|
250
|
-
## 8. Teams and several machines
|
|
251
|
-
|
|
252
|
-
SQLite is the default and needs no setup. To share memory, point claude-db at a database everyone can
|
|
253
|
-
reach:
|
|
69
|
+
By default memory is one SQLite file on your machine. To share it, point everyone at one database:
|
|
254
70
|
|
|
255
71
|
```bash
|
|
256
72
|
npm install -g pg
|
|
257
73
|
claude-db use "postgres://user:pass@host:5432/memory"
|
|
258
74
|
```
|
|
259
75
|
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
address, and warns if the database already holds tables that are not claude-db's. Give it a database
|
|
263
|
-
of its own.
|
|
264
|
-
|
|
265
|
-
- **Projects are matched by folder path.** Two machines share a project's memory when the project is
|
|
266
|
-
at the same path on both. If a repository lives at a different path on another machine, run
|
|
267
|
-
`claude-db merge <old-path> --yes` from the new location to bring the old memory across.
|
|
268
|
-
- **Personal rules stay personal.** A rule about how you like to work is filed under your git email,
|
|
269
|
-
so it follows you into every project and never reaches a teammate on a shared database. Set
|
|
270
|
-
`git config user.email` so it is filed under the right name. Everything else belongs to the
|
|
271
|
-
project and is shared.
|
|
272
|
-
- **Two databases, one memory.** `claude-db sync <url>` merges two databases in both directions, so a
|
|
273
|
-
laptop and a desktop can each work offline and reconcile later. `claude-db export` and
|
|
274
|
-
`claude-db import` do the same with a file.
|
|
275
|
-
- **Use a restricted account.** Connection strings are redacted whenever claude-db prints them, but
|
|
276
|
-
the account should only be able to reach its own database.
|
|
277
|
-
|
|
278
|
-
## 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.
|
|
279
78
|
|
|
280
|
-
|
|
281
|
-
| ------------------------- | ---------------------------------- | --------------------------------------------------------------------- |
|
|
282
|
-
| Now and then | `claude-db status` | Wired up, last recorded, open work, how many picks used today |
|
|
283
|
-
| Now and then | `claude-db stats` | What memory is made of, by kind and by area |
|
|
284
|
-
| After a big refactor | `claude-db scan` | Refreshes the code graph (it also refreshes at each session start) |
|
|
285
|
-
| When memory is stale | `claude-db prune --older-than 180` | A dry run that counts what would go; add `--yes` to delete |
|
|
286
|
-
| When something is wrong | `claude-db forget <id>` | Deletes a memory that turned out to be wrong, so it stops coming back |
|
|
287
|
-
| After moving a repository | `claude-db merge <old-path> --yes` | Brings memory filed under the old path across |
|
|
288
|
-
|
|
289
|
-
`claude-db uninstall --project` removes the hooks, the MCP entry and the instructions, and leaves your
|
|
290
|
-
memory untouched. Only `forget`, `prune` and `reset` delete memory, and the last two do nothing without
|
|
291
|
-
`--yes`.
|
|
292
|
-
|
|
293
|
-
## 10. Upgrading
|
|
79
|
+
## Upgrading
|
|
294
80
|
|
|
295
81
|
```bash
|
|
296
82
|
npm install -g claude-db
|
|
297
83
|
```
|
|
298
84
|
|
|
299
|
-
|
|
300
|
-
one-time jobs may run in the background, and none of them blocks a chat:
|
|
301
|
-
|
|
302
|
-
- repairing memory that an older version saved badly (`claude-db flush --repair`),
|
|
303
|
-
- re-applying secret redaction to everything already saved (`claude-db redact`),
|
|
304
|
-
- turning older chats into facts, which carries on over the next sessions within the daily limit.
|
|
305
|
-
|
|
306
|
-
Hooks that an earlier install registered are brought up to date automatically at session start, so a
|
|
307
|
-
new hook arrives without running `install` again. The first chat after you get facts says so once, and
|
|
308
|
-
how to switch that off with `claude-db distill off`.
|
|
309
|
-
|
|
310
|
-
## 11. When something is off
|
|
311
|
-
|
|
312
|
-
| What you see | Check |
|
|
313
|
-
| ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
314
|
-
| 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 |
|
|
315
|
-
| 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 |
|
|
316
|
-
| 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 |
|
|
317
|
-
| `doctor` says `registered 2x` | Run `claude-db install` again. It replaces its own entries |
|
|
318
|
-
| Install stops with a Node version message | Upgrade to Node 22.16 or newer |
|
|
319
|
-
| `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 |
|
|
320
|
-
| A moved repository looks empty | Memory is filed by folder path. Run `claude-db merge <old-path> --yes` |
|
|
321
|
-
| Search got worse after adding the embedding model | Run `claude-db reembed` |
|
|
322
|
-
|
|
323
|
-
The [troubleshooting page](https://claude-db.vercel.app/docs/troubleshooting) covers the rest.
|
|
85
|
+
Then restart Claude Code. Memory is kept.
|
|
324
86
|
|
|
325
|
-
##
|
|
87
|
+
## When something is off
|
|
326
88
|
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
| `~/.claude-memory/pick/` | Picks in flight and today's pick count |
|
|
333
|
-
| `~/.claude-memory/distill/` | Today's fact-making count |
|
|
334
|
-
| `~/.claude-memory/reingest/`, `redact/` | Marks that a one-time job has finished, per project or database |
|
|
335
|
-
| `.claude/settings.local.json` | The hooks, for a project install |
|
|
336
|
-
| `.mcp.json` | The MCP server, for a project install |
|
|
337
|
-
| `CLAUDE.local.md` | The standing instruction to search memory |
|
|
338
|
-
| `.claude/skills/cdb-scan/` | The `/cdb-scan` skill |
|
|
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.
|
|
339
94
|
|
|
340
|
-
|
|
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.
|
|
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": {
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: catchup
|
|
3
|
+
description: Answer "where did I stop?" for this project. Gives three short groups, done, open and next, taken from the last chat, the recorded to-dos, the last handoff note and git. Use when the user comes back to a project, starts a new chat, or asks where they left off. It writes nothing.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Where did I stop?
|
|
7
|
+
|
|
8
|
+
Run this from the project root:
|
|
9
|
+
|
|
10
|
+
```bash
|
|
11
|
+
claude-db catchup
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
It prints what memory and git know about this project, in plain text. Some parts may be missing. A part
|
|
15
|
+
with nothing in it is left out.
|
|
16
|
+
|
|
17
|
+
- `Last handoff` is a note the user or a teammate saved on purpose. Trust it most.
|
|
18
|
+
- `Last chat` is the newest recorded chat, with a few lines of the work done in it.
|
|
19
|
+
- `Still to do` are to-dos found in earlier chats.
|
|
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.
|
|
23
|
+
- `Git status` and `Recent commits` are the live state of the repository.
|
|
24
|
+
|
|
25
|
+
If the output is `Nothing recorded for this project yet.`, say exactly that and stop.
|
|
26
|
+
|
|
27
|
+
## Answer in three groups
|
|
28
|
+
|
|
29
|
+
Reply with these three groups and nothing else. Keep each to a few short lines in plain words.
|
|
30
|
+
|
|
31
|
+
**Done**: what is finished. Take it from the last chat, the recent commits and the handoff's `Done` line.
|
|
32
|
+
|
|
33
|
+
**Open**: what is started but not finished. Take it from `Not committed yet`, `Git status`, the to-dos and the
|
|
34
|
+
handoff's `Open` line.
|
|
35
|
+
|
|
36
|
+
**Next**: what to do first. Take it from the handoff's `Next` line, then from the to-dos.
|
|
37
|
+
|
|
38
|
+
## Rules
|
|
39
|
+
|
|
40
|
+
- Use only what the output shows. Do not read other files or search memory unless the user asks.
|
|
41
|
+
- Mark anything you are unsure of with `(guess)`. Never state a guess as a fact.
|
|
42
|
+
- If there is no clear next step, write `No clear next step found.` Do not invent one.
|
|
43
|
+
- Say how old the information is. Use the dates in the output, for example `Last chat (Oct 6)`.
|
|
44
|
+
- Do not save anything. Do not run any command that changes the repository.
|
|
45
|
+
|
|
46
|
+
_Shipped with claude-db. It is replaced when claude-db updates._
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: handoff
|
|
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
|
+
---
|
|
5
|
+
|
|
6
|
+
# Write a handoff note
|
|
7
|
+
|
|
8
|
+
## 1. Gather the facts
|
|
9
|
+
|
|
10
|
+
Run this from the project root to see what memory and git already know:
|
|
11
|
+
|
|
12
|
+
```bash
|
|
13
|
+
claude-db catchup
|
|
14
|
+
```
|
|
15
|
+
|
|
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. If it shows a `Last handoff`, that is the note you
|
|
18
|
+
will carry forward in step 2.
|
|
19
|
+
|
|
20
|
+
## 2. Write the note
|
|
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.
|
|
24
|
+
|
|
25
|
+
```
|
|
26
|
+
Handoff, Oct 7:
|
|
27
|
+
- Done: timers, queue, mail family.
|
|
28
|
+
- Open: PR #18 not merged.
|
|
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.
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
Lines:
|
|
37
|
+
|
|
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.
|
|
44
|
+
- Name real things: a file, a pull request number, a command, a decision. Do not write `various changes`.
|
|
45
|
+
- Use only what this chat or the output showed. Mark anything you are unsure of with `(guess)`.
|
|
46
|
+
- If there is no clear next step, write `- Next: no clear next step yet.` Do not invent one.
|
|
47
|
+
- Leave out secrets, tokens, passwords and personal data.
|
|
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
|
+
|
|
53
|
+
## 3. Save it
|
|
54
|
+
|
|
55
|
+
Call the `remember` memory tool once, with these exact values:
|
|
56
|
+
|
|
57
|
+
- `text`: the note
|
|
58
|
+
- `key`: `handoff`
|
|
59
|
+
- `kind`: `context`
|
|
60
|
+
- `tags`: `["handoff"]`
|
|
61
|
+
|
|
62
|
+
The key makes a new handoff replace the old one for this project, so there is one current note. The next
|
|
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.
|
|
65
|
+
|
|
66
|
+
## 4. Print it
|
|
67
|
+
|
|
68
|
+
Show the note in a code block so the user can paste it into a message or a pull request. Then say in one
|
|
69
|
+
line that it was saved, and that it replaces any earlier handoff for this project.
|
|
70
|
+
|
|
71
|
+
If the memory tool is not available, still print the note and say it was not saved.
|
|
72
|
+
|
|
73
|
+
## Sharing
|
|
74
|
+
|
|
75
|
+
A teammate sees the saved note when both of you use the same Postgres or MongoDB database. With the default
|
|
76
|
+
SQLite file on one machine, the printed note is the way to share it.
|
|
77
|
+
|
|
78
|
+
_Shipped with claude-db. It is replaced when claude-db updates._
|