claude-db 0.10.2 → 0.11.0

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 (96) hide show
  1. package/CHANGELOG.md +53 -0
  2. package/README.md +2 -1
  3. package/dist/catchup/gather.d.ts +17 -0
  4. package/dist/catchup/gather.js +39 -0
  5. package/dist/catchup/git-state.d.ts +7 -0
  6. package/dist/catchup/git-state.js +32 -0
  7. package/dist/catchup/render.d.ts +3 -0
  8. package/dist/catchup/render.js +41 -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/index.js +9 -0
  19. package/dist/cli/install.d.ts +6 -1
  20. package/dist/cli/install.js +8 -18
  21. package/dist/cli/paths.d.ts +1 -1
  22. package/dist/cli/paths.js +2 -2
  23. package/dist/cli/refresh.js +4 -12
  24. package/dist/cli/skills.d.ts +17 -0
  25. package/dist/cli/skills.js +65 -0
  26. package/dist/cli/usage.js +2 -0
  27. package/dist/config/schema.d.ts +3 -0
  28. package/dist/config/schema.js +8 -0
  29. package/dist/context.js +5 -2
  30. package/dist/facts/distill.d.ts +16 -1
  31. package/dist/facts/distill.js +20 -7
  32. package/dist/facts/handoff.d.ts +6 -0
  33. package/dist/facts/handoff.js +25 -0
  34. package/dist/facts/health.d.ts +3 -0
  35. package/dist/facts/health.js +10 -0
  36. package/dist/facts/model.d.ts +1 -0
  37. package/dist/facts/model.js +12 -0
  38. package/dist/facts/start.js +16 -5
  39. package/dist/hooks/payload.js +2 -0
  40. package/dist/store/adapter.d.ts +4 -2
  41. package/dist/store/adapter.js +1 -1
  42. package/dist/store/mongo/docs.d.ts +6 -0
  43. package/dist/store/mongo/filters.d.ts +2 -1
  44. package/dist/store/mongo/filters.js +9 -2
  45. package/dist/store/mongo/index.d.ts +5 -2
  46. package/dist/store/mongo/index.js +13 -2
  47. package/dist/store/mongo/observations.js +9 -5
  48. package/dist/store/mongo/project-links.d.ts +4 -0
  49. package/dist/store/mongo/project-links.js +13 -0
  50. package/dist/store/mongo/search.js +3 -0
  51. package/dist/store/mongo/sessions.d.ts +2 -2
  52. package/dist/store/mongo/sessions.js +5 -1
  53. package/dist/store/mongo/vectorSearch.js +3 -0
  54. package/dist/store/postgres/filters.d.ts +2 -1
  55. package/dist/store/postgres/filters.js +11 -4
  56. package/dist/store/postgres/index.d.ts +4 -2
  57. package/dist/store/postgres/index.js +7 -0
  58. package/dist/store/postgres/observations.js +15 -10
  59. package/dist/store/postgres/project-links.d.ts +3 -0
  60. package/dist/store/postgres/project-links.js +15 -0
  61. package/dist/store/postgres/schema.d.ts +2 -2
  62. package/dist/store/postgres/schema.js +9 -1
  63. package/dist/store/postgres/search.js +3 -0
  64. package/dist/store/postgres/sessions.d.ts +2 -2
  65. package/dist/store/postgres/sessions.js +9 -2
  66. package/dist/store/postgres/vectorSearch.js +3 -0
  67. package/dist/store/project-resolver.d.ts +16 -0
  68. package/dist/store/project-resolver.js +49 -0
  69. package/dist/store/project-scope.d.ts +5 -0
  70. package/dist/store/project-scope.js +16 -0
  71. package/dist/store/scoped-store.d.ts +3 -0
  72. package/dist/store/scoped-store.js +49 -0
  73. package/dist/store/sqlite/filters.d.ts +3 -2
  74. package/dist/store/sqlite/filters.js +23 -9
  75. package/dist/store/sqlite/index.d.ts +4 -2
  76. package/dist/store/sqlite/index.js +7 -0
  77. package/dist/store/sqlite/observations.js +13 -7
  78. package/dist/store/sqlite/project-links.d.ts +3 -0
  79. package/dist/store/sqlite/project-links.js +15 -0
  80. package/dist/store/sqlite/schema.sql +9 -0
  81. package/dist/store/sqlite/search.js +5 -0
  82. package/dist/store/sqlite/sessions.d.ts +2 -2
  83. package/dist/store/sqlite/sessions.js +8 -2
  84. package/dist/types.d.ts +4 -3
  85. package/dist/util/claude-binary.d.ts +23 -0
  86. package/dist/util/claude-binary.js +106 -0
  87. package/dist/util/claude-cli.d.ts +0 -1
  88. package/dist/util/claude-cli.js +2 -4
  89. package/dist/util/project-key.d.ts +7 -0
  90. package/dist/util/project-key.js +23 -0
  91. package/dist/util/remote-key.d.ts +3 -0
  92. package/dist/util/remote-key.js +50 -0
  93. package/docs/setup-guide.md +21 -13
  94. package/package.json +1 -1
  95. package/skills/catchup/SKILL.md +44 -0
  96. package/skills/handoff/SKILL.md +62 -0
@@ -102,3 +102,12 @@ CREATE TABLE IF NOT EXISTS scanned_files (
102
102
  scanned_at INTEGER NOT NULL,
103
103
  PRIMARY KEY (project, path)
104
104
  );
105
+
106
+ CREATE TABLE IF NOT EXISTS project_links (
107
+ folder TEXT NOT NULL,
108
+ project_key TEXT NOT NULL,
109
+ first_seen INTEGER NOT NULL,
110
+ PRIMARY KEY (folder, project_key)
111
+ );
112
+
113
+ CREATE INDEX IF NOT EXISTS idx_project_links_key ON project_links(project_key);
@@ -1,7 +1,10 @@
1
1
  import { toBuffer, toIndexEntry } from './rows.js';
2
2
  import { TAG_PREDICATE, appendScope, toMatchExpression } from './filters.js';
3
3
  import { cosine, unpackVector } from '../../util/vector.js';
4
+ import { noProjects } from '../project-scope.js';
4
5
  export async function searchKeyword(db, query) {
6
+ if (noProjects(query.project))
7
+ return [];
5
8
  const match = toMatchExpression(query.text, query.project);
6
9
  if (match === null)
7
10
  return [];
@@ -41,6 +44,8 @@ export async function searchKeyword(db, query) {
41
44
  return rows.map(toIndexEntry);
42
45
  }
43
46
  export async function searchVector(db, vector, query) {
47
+ if (noProjects(query.project))
48
+ return [];
44
49
  const conditions = ['embedding IS NOT NULL'];
45
50
  const params = [];
46
51
  appendScope(query, conditions, params, '');
@@ -1,7 +1,7 @@
1
1
  import type { DatabaseSync } from 'node:sqlite';
2
- import type { Session } from '../../types.js';
2
+ import type { ProjectFilter, Session } from '../../types.js';
3
3
  export declare function upsertSession(db: DatabaseSync, session: Session): Promise<void>;
4
4
  export declare function clearSummary(db: DatabaseSync, id: string): Promise<boolean>;
5
5
  export declare function getSession(db: DatabaseSync, id: string): Promise<Session | null>;
6
- export declare function recentSessions(db: DatabaseSync, project: string, limit: number): Promise<Session[]>;
6
+ export declare function recentSessions(db: DatabaseSync, project: ProjectFilter, limit: number): Promise<Session[]>;
7
7
  export declare function sessionProjects(db: DatabaseSync): Promise<string[]>;
@@ -1,5 +1,7 @@
1
+ import { projectClause } from './filters.js';
1
2
  import { toSession } from './rows.js';
2
3
  import { summaryTime } from '../session-time.js';
4
+ import { noProjects } from '../project-scope.js';
3
5
  export async function upsertSession(db, session) {
4
6
  db.prepare(`INSERT INTO sessions (id, project, started_at, ended_at, summary, updated_at, distilled_at)
5
7
  VALUES (?, ?, ?, ?, ?, ?, ?)
@@ -21,11 +23,15 @@ export async function getSession(db, id) {
21
23
  return row ? toSession(row) : null;
22
24
  }
23
25
  export async function recentSessions(db, project, limit) {
26
+ if (noProjects(project))
27
+ return [];
28
+ const params = [];
29
+ const scope = projectClause('project', project, params) ?? '1 = 1';
24
30
  const rows = db
25
31
  .prepare(`SELECT * FROM sessions
26
- WHERE project = ? AND summary IS NOT NULL
32
+ WHERE ${scope} AND summary IS NOT NULL
27
33
  ORDER BY started_at DESC LIMIT ?`)
28
- .all(project, limit);
34
+ .all(...params, limit);
29
35
  return rows.map(toSession);
30
36
  }
31
37
  export async function sessionProjects(db) {
package/dist/types.d.ts CHANGED
@@ -33,9 +33,10 @@ export interface ObservationIndexEntry {
33
33
  score: number;
34
34
  snippet?: string;
35
35
  }
36
+ export type ProjectFilter = string | readonly string[];
36
37
  export interface SearchQuery {
37
38
  text: string;
38
- project?: string;
39
+ project?: ProjectFilter;
39
40
  kind?: ObservationKind;
40
41
  tag?: string;
41
42
  since?: number;
@@ -47,12 +48,12 @@ export interface SearchQuery {
47
48
  }
48
49
  export interface RemoveFilter {
49
50
  ids?: string[];
50
- project?: string;
51
+ project?: ProjectFilter;
51
52
  kind?: ObservationKind;
52
53
  before?: number;
53
54
  }
54
55
  export interface ListFilter {
55
- project?: string;
56
+ project?: ProjectFilter;
56
57
  sessionId?: string;
57
58
  kind?: ObservationKind;
58
59
  status?: ObservationStatus;
@@ -0,0 +1,23 @@
1
+ export interface ProcessInfo {
2
+ parent: number;
3
+ exe: string;
4
+ }
5
+ export type InspectProcess = (pid: number) => ProcessInfo | null;
6
+ export declare function inspectWithPs(pid: number): ProcessInfo | null;
7
+ export declare function inspectProcess(pid: number): ProcessInfo | null;
8
+ export declare function findClaudeAncestor(start?: number, inspect?: InspectProcess): string | null;
9
+ export declare function rememberedBinary(file?: string): string | null;
10
+ export declare function rememberClaudeBinary(env?: NodeJS.ProcessEnv, file?: string, find?: () => string | null): void;
11
+ export type ClaudeSource = 'CLAUDE_CODE_EXECPATH' | 'saved path' | 'parent process' | 'PATH';
12
+ export interface ClaudeLocation {
13
+ path: string;
14
+ source: ClaudeSource;
15
+ }
16
+ export interface ClaudeLookup {
17
+ remembered: () => string | null;
18
+ ancestor: () => string | null;
19
+ onPath: (env: NodeJS.ProcessEnv) => string | null;
20
+ }
21
+ export declare function findOnPath(env?: NodeJS.ProcessEnv): string | null;
22
+ export declare function resolveClaude(env?: NodeJS.ProcessEnv, lookup?: Partial<ClaudeLookup>): ClaudeLocation | null;
23
+ export declare function claudeBinary(env?: NodeJS.ProcessEnv, lookup?: Partial<ClaudeLookup>): string;
@@ -0,0 +1,106 @@
1
+ import { execFileSync } from 'node:child_process';
2
+ import { accessSync, constants, mkdirSync, readFileSync, readlinkSync, statSync, writeFileSync, } from 'node:fs';
3
+ import { basename, delimiter, isAbsolute, join } from 'node:path';
4
+ import { CONFIG_DIR } from '../config/dir.js';
5
+ const REMEMBERED_FILE = join(CONFIG_DIR, 'claude-binary');
6
+ const MAX_ANCESTORS = 8;
7
+ function inspectOnLinux(pid) {
8
+ try {
9
+ const exe = readlinkSync(`/proc/${pid}/exe`);
10
+ const stat = readFileSync(`/proc/${pid}/stat`, 'utf8');
11
+ const parent = Number(stat.slice(stat.lastIndexOf(')') + 2).split(' ')[1]);
12
+ return Number.isInteger(parent) ? { parent, exe } : null;
13
+ }
14
+ catch {
15
+ return null;
16
+ }
17
+ }
18
+ export function inspectWithPs(pid) {
19
+ try {
20
+ const line = execFileSync('ps', ['-o', 'ppid=,comm=', '-p', String(pid)], {
21
+ encoding: 'utf8',
22
+ stdio: ['ignore', 'pipe', 'ignore'],
23
+ timeout: 1000,
24
+ }).trim();
25
+ const match = /^(\d+)\s+(.+)$/.exec(line);
26
+ return match?.[1] && match[2] ? { parent: Number(match[1]), exe: match[2] } : null;
27
+ }
28
+ catch {
29
+ return null;
30
+ }
31
+ }
32
+ export function inspectProcess(pid) {
33
+ if (process.platform === 'win32')
34
+ return null;
35
+ return process.platform === 'linux' ? inspectOnLinux(pid) : inspectWithPs(pid);
36
+ }
37
+ function isClaude(exe) {
38
+ return basename(exe) === 'claude';
39
+ }
40
+ export function findClaudeAncestor(start = process.ppid, inspect = inspectProcess) {
41
+ let pid = start;
42
+ for (let depth = 0; depth < MAX_ANCESTORS && pid > 1; depth++) {
43
+ const info = inspect(pid);
44
+ if (!info)
45
+ return null;
46
+ if (isClaude(info.exe))
47
+ return isAbsolute(info.exe) ? info.exe : null;
48
+ pid = info.parent;
49
+ }
50
+ return null;
51
+ }
52
+ export function rememberedBinary(file = REMEMBERED_FILE) {
53
+ try {
54
+ const path = readFileSync(file, 'utf8').trim();
55
+ return path !== '' && statSync(path, { throwIfNoEntry: false })?.isFile() ? path : null;
56
+ }
57
+ catch {
58
+ return null;
59
+ }
60
+ }
61
+ export function rememberClaudeBinary(env = process.env, file = REMEMBERED_FILE, find = findClaudeAncestor) {
62
+ const known = rememberedBinary(file);
63
+ const path = env['CLAUDE_CODE_EXECPATH'] || (known === null ? find() : null);
64
+ if (!path || path === known)
65
+ return;
66
+ try {
67
+ mkdirSync(CONFIG_DIR, { recursive: true });
68
+ writeFileSync(file, `${path}\n`, 'utf8');
69
+ }
70
+ catch { }
71
+ }
72
+ export function findOnPath(env = process.env) {
73
+ const names = process.platform === 'win32' ? ['claude.exe', 'claude.cmd'] : ['claude'];
74
+ for (const dir of (env['PATH'] ?? '').split(delimiter)) {
75
+ if (dir === '')
76
+ continue;
77
+ for (const name of names) {
78
+ const candidate = join(dir, name);
79
+ try {
80
+ if (!statSync(candidate).isFile())
81
+ continue;
82
+ accessSync(candidate, constants.X_OK);
83
+ return candidate;
84
+ }
85
+ catch { }
86
+ }
87
+ }
88
+ return null;
89
+ }
90
+ export function resolveClaude(env = process.env, lookup = {}) {
91
+ const { remembered = rememberedBinary, ancestor = findClaudeAncestor, onPath = findOnPath, } = lookup;
92
+ const fromEnv = env['CLAUDE_CODE_EXECPATH'];
93
+ if (fromEnv)
94
+ return { path: fromEnv, source: 'CLAUDE_CODE_EXECPATH' };
95
+ const saved = remembered();
96
+ if (saved)
97
+ return { path: saved, source: 'saved path' };
98
+ const parent = ancestor();
99
+ if (parent)
100
+ return { path: parent, source: 'parent process' };
101
+ const found = onPath(env);
102
+ return found ? { path: found, source: 'PATH' } : null;
103
+ }
104
+ export function claudeBinary(env = process.env, lookup = {}) {
105
+ return resolveClaude(env, lookup)?.path ?? 'claude';
106
+ }
@@ -9,7 +9,6 @@ export type HeadlessResult = {
9
9
  ok: false;
10
10
  reason: string;
11
11
  };
12
- export declare function claudeBinary(env?: NodeJS.ProcessEnv): string;
13
12
  export declare function runHeadlessResult(prompt: string, model: string, timeoutMs: number, options?: HeadlessOptions): Promise<HeadlessResult>;
14
13
  export declare function runHeadless(prompt: string, model: string, timeoutMs: number, options?: HeadlessOptions): Promise<string | null>;
15
14
  export declare function describeFailure(error: unknown, stderr: string, timeoutMs: number): string;
@@ -1,4 +1,5 @@
1
1
  import { execFile } from 'node:child_process';
2
+ import { claudeBinary } from './claude-binary.js';
2
3
  const MAX_BUFFER = 1024 * 1024;
3
4
  const REASON_CHARS = 120;
4
5
  const OPTIONAL_FLAGS = [
@@ -6,9 +7,6 @@ const OPTIONAL_FLAGS = [
6
7
  ['--no-session-persistence'],
7
8
  ];
8
9
  const UNKNOWN_OPTION = /unknown option '(--[\w-]+)'/i;
9
- export function claudeBinary(env = process.env) {
10
- return env['CLAUDE_CODE_EXECPATH'] || 'claude';
11
- }
12
10
  export async function runHeadlessResult(prompt, model, timeoutMs, options = {}) {
13
11
  let optional = [...OPTIONAL_FLAGS, ...(options.flags ?? [])];
14
12
  for (;;) {
@@ -29,7 +27,7 @@ export async function runHeadless(prompt, model, timeoutMs, options = {}) {
29
27
  export function describeFailure(error, stderr, timeoutMs) {
30
28
  const failure = typeof error === 'object' && error !== null ? error : {};
31
29
  if (failure.code === 'ENOENT') {
32
- return 'claude was not found: set CLAUDE_CODE_EXECPATH or put it on PATH';
30
+ return 'claude was not found: put it on PATH, or set CLAUDE_CODE_EXECPATH';
33
31
  }
34
32
  if (failure.code === 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER') {
35
33
  return 'the reply was larger than the 1 MB buffer';
@@ -0,0 +1,7 @@
1
+ export type RemoteReader = (folder: string, remote: string) => string | null;
2
+ export interface ProjectKeyOptions {
3
+ remote?: string;
4
+ readRemote?: RemoteReader;
5
+ }
6
+ export declare function readRemoteUrl(folder: string, remote: string): string | null;
7
+ export declare function projectKey(folder: string, options?: ProjectKeyOptions): string;
@@ -0,0 +1,23 @@
1
+ import { execFileSync } from 'node:child_process';
2
+ import { DEFAULT_REMOTE, isRemoteName, normalizeRemote } from './remote-key.js';
3
+ const GIT_TIMEOUT_MS = 3000;
4
+ export function readRemoteUrl(folder, remote) {
5
+ try {
6
+ const url = execFileSync('git', ['-C', folder, 'config', '--get', `remote.${remote}.url`], {
7
+ encoding: 'utf8',
8
+ stdio: ['ignore', 'pipe', 'ignore'],
9
+ timeout: GIT_TIMEOUT_MS,
10
+ }).trim();
11
+ return url.length > 0 ? url : null;
12
+ }
13
+ catch {
14
+ return null;
15
+ }
16
+ }
17
+ export function projectKey(folder, options = {}) {
18
+ const { remote = DEFAULT_REMOTE, readRemote = readRemoteUrl } = options;
19
+ if (!isRemoteName(remote))
20
+ return folder;
21
+ const url = readRemote(folder, remote);
22
+ return (url === null ? null : normalizeRemote(url)) ?? folder;
23
+ }
@@ -0,0 +1,3 @@
1
+ export declare const DEFAULT_REMOTE = "origin";
2
+ export declare function isRemoteName(name: string): boolean;
3
+ export declare function normalizeRemote(url: string): string | null;
@@ -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
+ }
@@ -67,8 +67,9 @@ Five hooks, which is why nothing needs to be run by hand afterwards:
67
67
  | PreToolUse (Bash and Grep) | Points symbol searches at the code graph instead of grep |
68
68
  | SessionEnd | Saves the last turn and starts turning the chat into facts |
69
69
 
70
- It also writes a standing instruction ("search memory before asking the user to re-explain") and the
71
- `/cdb-scan` skill.
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.
72
73
 
73
74
  ### Keep personal files out of git
74
75
 
@@ -124,13 +125,15 @@ test memory, searches for it, reads it back and deletes it, and tells you which
124
125
 
125
126
  A fresh install has nothing to recall. These steps fill it from what already exists.
126
127
 
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 |
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 |
134
137
 
135
138
  After you have used it for a session or two, a background job starts turning your older chats into
136
139
  **facts**: short rules, decisions with their reasons, dead ends and to-dos. It works newest chat first,
@@ -180,6 +183,7 @@ want to change.
180
183
  | `inject.perPrompt` | `true` | Show related memory with prompts at all | you want memory only at the start of a chat |
181
184
  | `inject.minOverlap` | `2` | Meaningful words a memory must share with the prompt | almost never; 2 was the best floor measured |
182
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`) |
183
187
  | `updates` | `notify` | `notify`, `auto` or `off` | you want updates installed for you, or never checked |
184
188
  | `embeddings.provider` | `auto` | `auto`, `local`, `builtin` or `none` | you install the optional embedding model, or want none |
185
189
 
@@ -262,9 +266,12 @@ was installed, since neither ships by default. `use` checks the database answers
262
266
  address, and warns if the database already holds tables that are not claude-db's. Give it a database
263
267
  of its own.
264
268
 
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.
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.
268
275
  - **Personal rules stay personal.** A rule about how you like to work is filed under your git email,
269
276
  so it follows you into every project and never reaches a teammate on a shared database. Set
270
277
  `git config user.email` so it is filed under the right name. Everything else belongs to the
@@ -317,7 +324,7 @@ how to switch that off with `claude-db distill off`.
317
324
  | `doctor` says `registered 2x` | Run `claude-db install` again. It replaces its own entries |
318
325
  | Install stops with a Node version message | Upgrade to Node 22.16 or newer |
319
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 |
320
- | A moved repository looks empty | Memory is filed by folder path. Run `claude-db merge <old-path> --yes` |
327
+ | A moved repository looks empty | A repository with a remote keeps its memory. With no remote, run `claude-db merge <old-path> --yes` |
321
328
  | Search got worse after adding the embedding model | Run `claude-db reembed` |
322
329
 
323
330
  The [troubleshooting page](https://claude-db.vercel.app/docs/troubleshooting) covers the rest.
@@ -336,5 +343,6 @@ The [troubleshooting page](https://claude-db.vercel.app/docs/troubleshooting) co
336
343
  | `.mcp.json` | The MCP server, for a project install |
337
344
  | `CLAUDE.local.md` | The standing instruction to search memory |
338
345
  | `.claude/skills/cdb-scan/` | The `/cdb-scan` skill |
346
+ | `.claude/skills/catchup/`, `handoff/` | The `/catchup` and `/handoff` skills |
339
347
 
340
348
  To delete everything claude-db has stored, remove `~/.claude-memory`.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "claude-db",
3
- "version": "0.10.2",
3
+ "version": "0.11.0",
4
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.",
5
5
  "license": "Apache-2.0",
6
6
  "type": "module",
@@ -0,0 +1,44 @@
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
+ - `Git status` and `Recent commits` are the live state of the repository.
22
+
23
+ If the output is `Nothing recorded for this project yet.`, say exactly that and stop.
24
+
25
+ ## Answer in three groups
26
+
27
+ Reply with these three groups and nothing else. Keep each to a few short lines in plain words.
28
+
29
+ **Done**: what is finished. Take it from the last chat, the recent commits and the handoff's `Done` line.
30
+
31
+ **Open**: what is started but not finished. Take it from `Not committed yet`, `Git status`, the to-dos and the
32
+ handoff's `Open` line.
33
+
34
+ **Next**: what to do first. Take it from the handoff's `Next` line, then from the to-dos.
35
+
36
+ ## Rules
37
+
38
+ - Use only what the output shows. Do not read other files or search memory unless the user asks.
39
+ - Mark anything you are unsure of with `(guess)`. Never state a guess as a fact.
40
+ - If there is no clear next step, write `No clear next step found.` Do not invent one.
41
+ - Say how old the information is. Use the dates in the output, for example `Last chat (Oct 6)`.
42
+ - Do not save anything. Do not run any command that changes the repository.
43
+
44
+ _Shipped with claude-db. It is replaced when claude-db updates._
@@ -0,0 +1,62 @@
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 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.
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.
18
+
19
+ ## 2. Write the note
20
+
21
+ Use this exact shape. The first line is the title and has today's date. Get it with `date '+%b %-d'`.
22
+
23
+ ```
24
+ Handoff, Oct 6:
25
+ - Done: timers, queue, mail family.
26
+ - Open: PR #18 not merged.
27
+ - Next: ask which retries to change on the worker queue.
28
+ ```
29
+
30
+ Rules for each line:
31
+
32
+ - One line each for `Done`, `Open` and `Next`. Keep each under about 120 characters.
33
+ - Name real things: a file, a pull request number, a command, a decision. Do not write `various changes`.
34
+ - Use only what this chat or the output showed. Mark anything you are unsure of with `(guess)`.
35
+ - If there is no clear next step, write `- Next: no clear next step yet.` Do not invent one.
36
+ - Leave out secrets, tokens, passwords and personal data.
37
+
38
+ ## 3. Save it
39
+
40
+ Call the `remember` memory tool once, with these exact values:
41
+
42
+ - `text`: the note
43
+ - `key`: `handoff`
44
+ - `kind`: `context`
45
+ - `tags`: `["handoff"]`
46
+
47
+ 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.
49
+
50
+ ## 4. Print it
51
+
52
+ Show the note in a code block so the user can paste it into a message or a pull request. Then say in one
53
+ line that it was saved, and that it replaces any earlier handoff for this project.
54
+
55
+ If the memory tool is not available, still print the note and say it was not saved.
56
+
57
+ ## Sharing
58
+
59
+ A teammate sees the saved note when both of you use the same Postgres or MongoDB database. With the default
60
+ SQLite file on one machine, the printed note is the way to share it.
61
+
62
+ _Shipped with claude-db. It is replaced when claude-db updates._