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.
Files changed (99) hide show
  1. package/CHANGELOG.md +66 -0
  2. package/README.md +41 -78
  3. package/dist/catchup/gather.d.ts +18 -0
  4. package/dist/catchup/gather.js +46 -0
  5. package/dist/catchup/git-state.d.ts +9 -0
  6. package/dist/catchup/git-state.js +35 -0
  7. package/dist/catchup/render.d.ts +3 -0
  8. package/dist/catchup/render.js +49 -0
  9. package/dist/cli/backfill-output.d.ts +13 -0
  10. package/dist/cli/backfill-output.js +78 -0
  11. package/dist/cli/commands/catchup.d.ts +1 -0
  12. package/dist/cli/commands/catchup.js +14 -0
  13. package/dist/cli/commands/distill.js +13 -2
  14. package/dist/cli/commands/doctor.d.ts +2 -0
  15. package/dist/cli/commands/doctor.js +42 -3
  16. package/dist/cli/commands/insight.js +2 -1
  17. package/dist/cli/commands/setup.js +29 -9
  18. package/dist/cli/files.d.ts +2 -0
  19. package/dist/cli/files.js +15 -1
  20. package/dist/cli/index.js +9 -0
  21. package/dist/cli/install.d.ts +6 -1
  22. package/dist/cli/install.js +11 -20
  23. package/dist/cli/paths.d.ts +1 -1
  24. package/dist/cli/paths.js +2 -2
  25. package/dist/cli/refresh.js +4 -12
  26. package/dist/cli/skills.d.ts +17 -0
  27. package/dist/cli/skills.js +70 -0
  28. package/dist/cli/usage.js +2 -0
  29. package/dist/config/schema.d.ts +3 -0
  30. package/dist/config/schema.js +8 -0
  31. package/dist/context.js +5 -2
  32. package/dist/facts/distill.d.ts +16 -3
  33. package/dist/facts/distill.js +22 -31
  34. package/dist/facts/handoff.d.ts +6 -0
  35. package/dist/facts/handoff.js +35 -0
  36. package/dist/facts/health.d.ts +3 -0
  37. package/dist/facts/health.js +10 -0
  38. package/dist/facts/known.d.ts +4 -0
  39. package/dist/facts/known.js +38 -0
  40. package/dist/facts/model.d.ts +1 -0
  41. package/dist/facts/model.js +12 -0
  42. package/dist/facts/ops.d.ts +1 -1
  43. package/dist/facts/ops.js +4 -2
  44. package/dist/facts/start.js +20 -5
  45. package/dist/store/adapter.d.ts +4 -2
  46. package/dist/store/adapter.js +1 -1
  47. package/dist/store/mongo/docs.d.ts +6 -0
  48. package/dist/store/mongo/filters.d.ts +2 -1
  49. package/dist/store/mongo/filters.js +9 -2
  50. package/dist/store/mongo/index.d.ts +5 -2
  51. package/dist/store/mongo/index.js +13 -2
  52. package/dist/store/mongo/observations.js +9 -5
  53. package/dist/store/mongo/project-links.d.ts +4 -0
  54. package/dist/store/mongo/project-links.js +13 -0
  55. package/dist/store/mongo/search.js +3 -0
  56. package/dist/store/mongo/sessions.d.ts +2 -2
  57. package/dist/store/mongo/sessions.js +5 -1
  58. package/dist/store/mongo/vectorSearch.js +3 -0
  59. package/dist/store/postgres/filters.d.ts +2 -1
  60. package/dist/store/postgres/filters.js +11 -4
  61. package/dist/store/postgres/index.d.ts +4 -2
  62. package/dist/store/postgres/index.js +7 -0
  63. package/dist/store/postgres/observations.js +15 -10
  64. package/dist/store/postgres/project-links.d.ts +3 -0
  65. package/dist/store/postgres/project-links.js +15 -0
  66. package/dist/store/postgres/schema.d.ts +2 -2
  67. package/dist/store/postgres/schema.js +9 -1
  68. package/dist/store/postgres/search.js +3 -0
  69. package/dist/store/postgres/sessions.d.ts +2 -2
  70. package/dist/store/postgres/sessions.js +9 -2
  71. package/dist/store/postgres/vectorSearch.js +3 -0
  72. package/dist/store/project-resolver.d.ts +16 -0
  73. package/dist/store/project-resolver.js +49 -0
  74. package/dist/store/project-scope.d.ts +5 -0
  75. package/dist/store/project-scope.js +16 -0
  76. package/dist/store/scoped-store.d.ts +3 -0
  77. package/dist/store/scoped-store.js +49 -0
  78. package/dist/store/sqlite/filters.d.ts +3 -2
  79. package/dist/store/sqlite/filters.js +23 -9
  80. package/dist/store/sqlite/index.d.ts +4 -2
  81. package/dist/store/sqlite/index.js +7 -0
  82. package/dist/store/sqlite/observations.js +13 -7
  83. package/dist/store/sqlite/project-links.d.ts +3 -0
  84. package/dist/store/sqlite/project-links.js +15 -0
  85. package/dist/store/sqlite/schema.sql +9 -0
  86. package/dist/store/sqlite/search.js +5 -0
  87. package/dist/store/sqlite/sessions.d.ts +2 -2
  88. package/dist/store/sqlite/sessions.js +8 -2
  89. package/dist/types.d.ts +4 -3
  90. package/dist/util/claude-binary.d.ts +15 -1
  91. package/dist/util/claude-binary.js +39 -7
  92. package/dist/util/project-key.d.ts +7 -0
  93. package/dist/util/project-key.js +23 -0
  94. package/dist/util/remote-key.d.ts +3 -0
  95. package/dist/util/remote-key.js +50 -0
  96. package/docs/setup-guide.md +47 -291
  97. package/package.json +2 -2
  98. package/skills/catchup/SKILL.md +46 -0
  99. 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
+ }
@@ -1,36 +1,13 @@
1
- # Setup guide: get the best results from claude-db
1
+ # Setup guide
2
2
 
3
- Last updated: 2026-10-06. This guide describes the version in this repository, including everything
4
- listed under 0.10.0 in the [changelog](../CHANGELOG.md).
5
-
6
- claude-db works after one install command. This guide covers what comes after that: how to check it
7
- is working, how to give it a head start, which habits and settings change the results most, and what
8
- it costs. Where a recommendation rests on a measurement, the number is given. The measurements are in
9
- [memory-improvements.md](https://github.com/Avijit07x/claude-db/blob/main/docs/memory-improvements.md), and how it all works is in
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
- | You need | Why |
28
- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
29
- | Node 22.16 or newer | The default database is Node's built-in SQLite. Before 22.16 it either needs a flag or has no full-text search. An older Node is refused at install with a clear message. Check with `node -v` |
30
- | A git repository | `scan` and `seed` read your project through git, and the project's folder path is what its memory is filed under |
31
- | Claude Code, logged in | Two background features call Claude Haiku through your own login (see [cost and privacy](#7-cost-and-privacy)). The terminal CLI and the VS Code extension both work |
32
-
33
- Nothing else is required. Postgres, MongoDB and the local embedding model are optional.
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
- Every command also works as `cdb`.
44
-
45
- ### One project or the whole machine
46
-
47
- | | `claude-db install --project` | `claude-db install` |
48
- | ------------------- | ----------------------------------------- | ----------------------------------------------- |
49
- | Applies to | this repository only | every project you open on this machine |
50
- | Hooks go in | `.claude/settings.local.json` in the repo | `~/.claude/settings.json` |
51
- | Memory instructions | `CLAUDE.local.md` in the repo | `~/.claude/CLAUDE.md` |
52
- | MCP server in | `.mcp.json` in the repo | your Claude Code user config (`~/.claude.json`) |
53
- | Good for | trying it, or keeping it off some repos | using it everywhere without thinking about it |
54
-
55
- Memory itself is always one database for the whole machine (`~/.claude-memory/memory.db`), filed by
56
- project. The choice above only decides where claude-db is switched on.
20
+ Then restart Claude Code. Hooks and the MCP server load only when Claude Code starts.
57
21
 
58
- ### What install registers
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
- Five hooks, which is why nothing needs to be run by hand afterwards:
61
-
62
- | Hook | What it does |
63
- | -------------------------- | ----------------------------------------------------------------------- |
64
- | SessionStart | Shows what matters at the start of a chat, and starts background upkeep |
65
- | UserPromptSubmit | Saves the previous turn and looks for memory that fits your new prompt |
66
- | PreToolUse (every tool) | Hands Claude the memory Haiku picked, with its first tool call |
67
- | PreToolUse (Bash and Grep) | Points symbol searches at the code graph instead of grep |
68
- | SessionEnd | Saves the last turn and starts turning the chat into facts |
69
-
70
- It also writes a standing instruction ("search memory before asking the user to re-explain") and the
71
- `/cdb-scan` skill.
72
-
73
- ### Keep personal files out of git
74
-
75
- `.mcp.json` holds an absolute path on your machine, so committing it breaks the project for everyone
76
- else. `CLAUDE.local.md` and `.claude/settings.local.json` are meant to be personal too. Make sure all
77
- three are ignored:
78
-
79
- ```bash
80
- printf '\n.mcp.json\nCLAUDE.local.md\n.claude/settings.local.json\n' >> .gitignore
81
- ```
82
-
83
- The installer only reminds you about `.mcp.json`, and only when no `.gitignore` lists it.
84
-
85
- ### Restart Claude Code
86
-
87
- The MCP server and the hooks are loaded when Claude Code starts. A session that was already open does
88
- not have them.
89
-
90
- ## 3. Check that it works
91
-
92
- ```bash
93
- claude-db status
94
- ```
95
-
96
- Right after install you should see this, with your own paths:
97
-
98
- ```text
99
- project : ~/shop
100
- database : ~/.claude-memory/memory.db
101
- hooks : this project
102
- mcp : registered (~/shop/.mcp.json)
103
- sessions : 0 recorded for this project
104
- worked : never
105
- recorded : never
106
- facts : 0 for this project, 0 about you
107
- waiting : 0 chat(s) not yet turned into facts
108
- pick : on (haiku), 0 of 150 picks used today
109
- ```
110
-
111
- "Nothing recorded yet" is normal here. Memory is written as you work, only for turns that changed
112
- something, so a chat of questions leaves nothing behind. After your first real session, `sessions`
113
- and `recorded` fill in.
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` shows the version, the database, whether it can be reached, the embedder, and whether the
120
- hooks are wired once each (`wiring : ok`). `claude-db doctor --deep` goes further: it writes one
121
- test memory, searches for it, reads it back and deletes it, and tells you which step failed if any.
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. These steps fill it from what already exists.
126
-
127
- | Step | Command | What it does | Cost |
128
- | ------------------------------------ | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
129
- | Load your past chats | `claude-db flush` | Reads the chats Claude Code already saved for this project and turns them into memory. Claude Code keeps chat files for about 30 days, so do this early | none |
130
- | Map the code | `claude-db scan` | Stores every symbol and how they connect. About a second on a mid-size repo. After the first scan it refreshes itself at each session start | none |
131
- | Read the git history | `claude-db seed --from-git` | Turns your commit history into memory so search has something to match | none |
132
- | Or do the mapping from inside Claude | `/cdb-scan` | A skill that builds the graph, then writes five notes about your stack, layout, conventions, workflows and architecture | a normal chat turn |
133
- | State your standing rules | `claude-db remember "always use pnpm in this repo"` | Stored as a rule for this project and recalled when relevant | none |
37
+ A fresh install has nothing to recall. Run these once:
134
38
 
135
- After you have used it for a session or two, a background job starts turning your older chats into
136
- **facts**: short rules, decisions with their reasons, dead ends and to-dos. It works newest chat first,
137
- only on the last 90 days, and at most 30 Haiku calls a day. `claude-db distill` shows how many chats
138
- are still waiting. Claude Code's own memory files for the project (`~/.claude/projects/*/memory/`) are
139
- imported as facts too, at no cost.
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
- ## 5. Work in ways that help memory
45
+ Old chats are also turned into short facts in the background, newest first, within a daily limit.
142
46
 
143
- These follow from how recall works. The numbers come from replaying 300 real prompts; see
144
- [memory-improvements.md](https://github.com/Avijit07x/claude-db/blob/main/docs/memory-improvements.md).
47
+ ## 5. Work in ways that help
145
48
 
146
- - **Be specific.** A prompt needs at least two meaningful words, and a past memory is only considered
147
- if it shares at least two of them with your prompt. "Make the order feed reconnect with backoff"
148
- finds things. "ok", "continue" and "do it" find nothing, on purpose.
149
- - **Expect memory with Claude's first tool call, not before your prompt.** Haiku reads the closest
150
- ten memories and picks at most two, only when they carry something specific for this task. Most
151
- prompts get none: in testing about 30% did, and about 6 to 7 in 10 of what was shown was judged
152
- useful. A turn in which Claude uses no tools never shows a pick.
153
- - **Say why.** "We chose a websocket because polling hammered the API" becomes a decision with its
154
- reason. "That approach failed because..." becomes a dead end. These are what a later chat needs.
155
- - **State a rule once, plainly.** Tell Claude to remember it, or run `claude-db remember`.
156
- - **Commit finished work.** Work that changed files stays listed as "Not committed" in `status` and at
157
- the start of a chat until those files are committed.
158
- - **Wrap anything private in `<private>...</private>`.** It is removed before the turn is saved.
159
- - **Use `/compact` freely.** When a chat is compacted, its own decisions and open work are put back.
160
- - **Keep `CLAUDE.md` for a stable overview of the project.** claude-db stores what happened, which is
161
- a different job.
162
- - **Look at what it holds.** `claude-db search <words>`, `claude-db stats`, and `claude-db view` for a
163
- page in the browser.
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
- ## 6. Settings
56
+ ## Cost and privacy
166
57
 
167
- Settings live in `~/.claude-memory/config.json`. The file is optional and every key has a default.
168
- It is created the first time a command changes a setting, such as `claude-db pick off`,
169
- `claude-db distill off` or `claude-db use`. Edit it by hand for the rest, and list only the keys you
170
- want to change.
58
+ Two small background features call Claude Haiku through your own login:
171
59
 
172
- | Key | Default | What it does | Change it when |
173
- | ---------------------- | -------- | ---------------------------------------------------------------- | ----------------------------------------------------------- |
174
- | `pick.enabled` | `true` | Let Haiku pick the memory shown with a prompt | you want no Claude usage for this (`claude-db pick off`) |
175
- | `pick.dailyLimit` | `150` | Most picks a day. After that, only strong word matches are shown | you work a lot in one day |
176
- | `pick.model` | `haiku` | `haiku`, `sonnet` or `opus` | almost never; Haiku was the one measured |
177
- | `distill.enabled` | `true` | Turn finished chats into facts | you want no Claude usage for this (`claude-db distill off`) |
178
- | `distill.dailyLimit` | `30` | Most fact-making calls a day | you have many old chats to catch up on |
179
- | `distill.backfillDays` | `90` | How far back older chats are turned into facts | you want a shorter or longer reach |
180
- | `inject.perPrompt` | `true` | Show related memory with prompts at all | you want memory only at the start of a chat |
181
- | `inject.minOverlap` | `2` | Meaningful words a memory must share with the prompt | almost never; 2 was the best floor measured |
182
- | `inject.promptResults` | `2` | Most memories shown with one prompt | you want more or fewer lines |
183
- | `updates` | `notify` | `notify`, `auto` or `off` | you want updates installed for you, or never checked |
184
- | `embeddings.provider` | `auto` | `auto`, `local`, `builtin` or `none` | you install the optional embedding model, or want none |
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
- ### Three ready-made setups
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
- **The default** needs no file. It uses Haiku for picking and for facts, inside the daily limits.
67
+ ## Teams and several machines
189
68
 
190
- **No Claude usage.** Memory is still recorded and searched, but nothing calls Claude:
191
-
192
- ```json
193
- {
194
- "pick": { "enabled": false },
195
- "distill": { "enabled": false }
196
- }
197
- ```
198
-
199
- The cost is quality. Without Haiku, a prompt only gets memory when the closest one shares four
200
- meaningful words with it. In testing that showed memory on about 12% of prompts, and it was useful
201
- 43% of the time, against about 6 to 7 in 10 with Haiku. No new facts are made, so the start of a
202
- chat shows the facts it already has, or recent session summaries if there are none.
203
-
204
- **Heavy use.** Raise the limits if you hit them. `claude-db pick` and `claude-db distill` show how
205
- much of today's limit is used:
206
-
207
- ```json
208
- {
209
- "pick": { "dailyLimit": 400 },
210
- "distill": { "dailyLimit": 60 }
211
- }
212
- ```
213
-
214
- ### Better embeddings are optional
215
-
216
- The built-in embedder works without installing anything. For semantic matching in `search`:
217
-
218
- ```bash
219
- npm install -g @xenova/transformers
220
- claude-db reembed
221
- ```
222
-
223
- This is a large download (about 200 MB of libraries plus a model). It is not needed for picking, and
224
- its effect on the memory shown with prompts was not measured.
225
-
226
- ## 7. Cost and privacy
227
-
228
- Nothing leaves your machine except the things below, and each can be turned off.
229
-
230
- | What | When | What is sent | Cost | Limit | Turn it off |
231
- | ------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ---------- | ----------------------- |
232
- | Picking | A prompt has related memory | Your prompt, the end of Claude's previous reply, and up to ten memory excerpts of 600 characters, all redacted | About 3,000 input and 100 output Haiku tokens per pick | 150 a day | `claude-db pick off` |
233
- | Facts | After a chat ends | The chat's saved, redacted text, in pieces of about 40,000 characters | One Haiku call per piece | 30 a day | `claude-db distill off` |
234
- | Update check | Once a day | A request to the npm registry | none | once a day | `"updates": "off"` |
235
- | Your database | Only if you set a remote one | Your memory | depends on the host | none | `claude-db use <path>` |
236
-
237
- Both Haiku features go through your own Claude Code login, so they count against your plan like any
238
- other use. Haiku is the lightest model, and a pick is small next to an ordinary chat turn. A failed
239
- call pauses that feature for an hour, 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
- Use `mongodb` and a `mongodb+srv://` address for MongoDB. Install the driver the same way claude-db
261
- was installed, since neither ships by default. `use` checks the database answers before it saves the
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
- | How often | Command | Why |
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
- or `claude-db update`. Then restart Claude Code once. At the first session after an update, a few
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
- ## 12. Where things live
87
+ ## When something is off
326
88
 
327
- | Path | What it is |
328
- | --------------------------------------- | ----------------------------------------------------------------------- |
329
- | `~/.claude-memory/memory.db` | The default SQLite database |
330
- | `~/.claude-memory/config.json` | Your settings (optional) |
331
- | `~/.claude-memory/cursors/` | How far each chat has been read, and what a chat has already been shown |
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
- To delete everything claude-db has stored, remove `~/.claude-memory`.
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.10.3",
4
- "description": "Persistent memory for Claude Code. Captures why decisions were made, not just which files changed. Bring your own database: SQLite, MongoDB or Postgres. No cloud, no subscription.",
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._