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 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
- **Persistent memory for Claude Code. Bring your own database.**
3
+ **Free, open-source memory for Claude Code. Your own database, no cloud, no subscription.**
4
4
 
5
5
  [![npm](https://img.shields.io/npm/v/claude-db.svg)](https://www.npmjs.com/package/claude-db)
6
6
  [![CI](https://github.com/Avijit07x/claude-db/actions/workflows/ci.yml/badge.svg)](https://github.com/Avijit07x/claude-db/actions/workflows/ci.yml)
@@ -12,112 +12,74 @@
12
12
 
13
13
  ---
14
14
 
15
- ## Every session starts from zero
15
+ ## Why
16
16
 
17
- You spent an hour yesterday explaining why the store has three adapters, which
18
- approach you tried and dropped, and why one function must not be touched. Today
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 gives Claude a memory that lasts, and a map of your code so it stops
22
- working out what calls what from scratch.
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 you get
23
+ ## What it does
25
24
 
26
- - **A memory that carries over.** When a chat ends, its decisions, dead ends and
27
- rules are saved as short facts, and the next chat starts by seeing them.
28
- - **The right memory with each prompt.** Claude Haiku picks the one or two
29
- earlier memories that fit what you just asked. That costs about 20 tokens a
30
- prompt on average, and nothing on 69% of prompts.
31
- - **A code graph.** Who defines or calls a symbol, answered in one call: 2.0x
32
- cheaper than grep and reading files, measured on eight real symbols.
33
- - **Your own database.** SQLite by default, or Postgres or MongoDB to share
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. Capture and recall are hooks, so there is nothing else to
46
- run.
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
- | Command | What it does |
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
- Every other command, including `search`, `remember`, `sync` and `export`, is in
74
- the [CLI reference](https://claude-db.vercel.app/docs/cli).
50
+ ## Everyday use
75
51
 
76
- ## Use another database
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
- ```bash
79
- claude-db use "postgres://user:pass@host:5432/memory"
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. Three things use the network, and each has
89
- an off switch:
90
-
91
- - **When a chat ends**, its saved, redacted text is sent once to Claude Haiku
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
- - [Documentation site](https://claude-db.vercel.app/docs): the
112
- [CLI reference](https://claude-db.vercel.app/docs/cli),
113
- [MCP tools](https://claude-db.vercel.app/docs/mcp-tools),
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): every number,
120
- including the symbols where plain grep wins
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
@@ -11,6 +11,7 @@ export interface CatchupData {
11
11
  work: string[];
12
12
  } | null;
13
13
  todos: string[];
14
+ decisions: string[];
14
15
  uncommitted: string[];
15
16
  git: GitState | null;
16
17
  }
@@ -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 todos = onePerKey(facts.filter((obs) => obs.status !== 'replaced'))
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
  };
@@ -1,4 +1,6 @@
1
1
  export interface GitState {
2
+ branch: string | null;
3
+ changed: number;
2
4
  status: string[];
3
5
  hiddenStatusLines: number;
4
6
  commits: string[];
@@ -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,
@@ -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
  ];
@@ -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
+ }
@@ -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
- writeJson(path, settings);
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
- writeJson(mcpPath, mcpConfig);
136
+ save(mcpPath, mcpConfig);
136
137
  return path;
137
138
  }
138
139
  function hookCommand(distDir, file) {
@@ -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'];
@@ -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;
@@ -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, factKey, factToObservation, factType, onePerKey, youScope, } from './model.js';
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 reply = await run(buildDistillPrompt(chat, existing), ctx.config.distill.model, TIMEOUT_MS);
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 = [];
@@ -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
- return obs.body
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
+ }
@@ -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>',
@@ -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) => [line, index === 0 ? handoff.id : null]);
68
+ return handoffBodyLines(handoff).map((line, index) => [
69
+ index === 0 ? `${line} (${toShortId(handoff.id)})` : line,
70
+ index === 0 ? handoff.id : null,
71
+ ]);
68
72
  }
@@ -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,309 +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 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` shows the version, the database, whether it can be reached, the embedder, and whether the
121
- hooks are wired once each (`wiring : ok`). `claude-db doctor --deep` goes further: it writes one
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. These steps fill it from what already exists.
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
- After you have used it for a session or two, a background job starts turning your older chats into
139
- **facts**: short rules, decisions with their reasons, dead ends and to-dos. It works newest chat first,
140
- only on the last 90 days, and at most 30 Haiku calls a day. `claude-db distill` shows how many chats
141
- are still waiting. Claude Code's own memory files for the project (`~/.claude/projects/*/memory/`) are
142
- 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 |
143
44
 
144
- ## 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.
145
46
 
146
- These follow from how recall works. The numbers come from replaying 300 real prompts; see
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.** A prompt needs at least two meaningful words, and a past memory is only considered
150
- if it shares at least two of them with your prompt. "Make the order feed reconnect with backoff"
151
- finds things. "ok", "continue" and "do it" find nothing, on purpose.
152
- - **Expect memory with Claude's first tool call, not before your prompt.** Haiku reads the closest
153
- ten memories and picks at most two, only when they carry something specific for this task. Most
154
- prompts get none: in testing about 30% did, and about 6 to 7 in 10 of what was shown was judged
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
- ## 6. Settings
56
+ ## Cost and privacy
169
57
 
170
- Settings live in `~/.claude-memory/config.json`. The file is optional and every key has a default.
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
- | Key | Default | What it does | Change it when |
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
- ### 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.
191
66
 
192
- **The default** needs no file. It uses Haiku for picking and for facts, inside the daily limits.
67
+ ## Teams and several machines
193
68
 
194
- **No Claude usage.** Memory is still recorded and searched, but nothing calls Claude:
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
- Use `mongodb` and a `mongodb+srv://` address for MongoDB. Install the driver the same way claude-db
265
- was installed, since neither ships by default. `use` checks the database answers before it saves the
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
- | How often | Command | Why |
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
- or `claude-db update`. Then restart Claude Code once. At the first session after an update, a few
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
- ## 12. Where things live
87
+ ## When something is off
333
88
 
334
- | Path | What it is |
335
- | --------------------------------------- | ----------------------------------------------------------------------- |
336
- | `~/.claude-memory/memory.db` | The default SQLite database |
337
- | `~/.claude-memory/config.json` | Your settings (optional) |
338
- | `~/.claude-memory/cursors/` | How far each chat has been read, and what a chat has already been shown |
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
- 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.11.0",
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": {
@@ -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.
@@ -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 comes next. 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.
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
- Use this exact shape. The first line is the title and has today's date. Get it with `date '+%b %-d'`.
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 6:
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
- Rules for each line:
36
+ Lines:
31
37
 
32
- - One line each for `Done`, `Open` and `Next`. Keep each under about 120 characters.
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