claude-db 0.10.3 → 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.
- package/CHANGELOG.md +39 -0
- package/README.md +2 -1
- package/dist/catchup/gather.d.ts +17 -0
- package/dist/catchup/gather.js +39 -0
- package/dist/catchup/git-state.d.ts +7 -0
- package/dist/catchup/git-state.js +32 -0
- package/dist/catchup/render.d.ts +3 -0
- package/dist/catchup/render.js +41 -0
- package/dist/cli/backfill-output.d.ts +13 -0
- package/dist/cli/backfill-output.js +78 -0
- package/dist/cli/commands/catchup.d.ts +1 -0
- package/dist/cli/commands/catchup.js +14 -0
- package/dist/cli/commands/distill.js +13 -2
- package/dist/cli/commands/doctor.d.ts +2 -0
- package/dist/cli/commands/doctor.js +42 -3
- package/dist/cli/commands/insight.js +2 -1
- package/dist/cli/commands/setup.js +29 -9
- package/dist/cli/index.js +9 -0
- package/dist/cli/install.d.ts +6 -1
- package/dist/cli/install.js +8 -18
- package/dist/cli/paths.d.ts +1 -1
- package/dist/cli/paths.js +2 -2
- package/dist/cli/refresh.js +4 -12
- package/dist/cli/skills.d.ts +17 -0
- package/dist/cli/skills.js +65 -0
- package/dist/cli/usage.js +2 -0
- package/dist/config/schema.d.ts +3 -0
- package/dist/config/schema.js +8 -0
- package/dist/context.js +5 -2
- package/dist/facts/distill.d.ts +16 -1
- package/dist/facts/distill.js +20 -7
- package/dist/facts/handoff.d.ts +6 -0
- package/dist/facts/handoff.js +25 -0
- package/dist/facts/health.d.ts +3 -0
- package/dist/facts/health.js +10 -0
- package/dist/facts/model.d.ts +1 -0
- package/dist/facts/model.js +12 -0
- package/dist/facts/start.js +16 -5
- package/dist/store/adapter.d.ts +4 -2
- package/dist/store/adapter.js +1 -1
- package/dist/store/mongo/docs.d.ts +6 -0
- package/dist/store/mongo/filters.d.ts +2 -1
- package/dist/store/mongo/filters.js +9 -2
- package/dist/store/mongo/index.d.ts +5 -2
- package/dist/store/mongo/index.js +13 -2
- package/dist/store/mongo/observations.js +9 -5
- package/dist/store/mongo/project-links.d.ts +4 -0
- package/dist/store/mongo/project-links.js +13 -0
- package/dist/store/mongo/search.js +3 -0
- package/dist/store/mongo/sessions.d.ts +2 -2
- package/dist/store/mongo/sessions.js +5 -1
- package/dist/store/mongo/vectorSearch.js +3 -0
- package/dist/store/postgres/filters.d.ts +2 -1
- package/dist/store/postgres/filters.js +11 -4
- package/dist/store/postgres/index.d.ts +4 -2
- package/dist/store/postgres/index.js +7 -0
- package/dist/store/postgres/observations.js +15 -10
- package/dist/store/postgres/project-links.d.ts +3 -0
- package/dist/store/postgres/project-links.js +15 -0
- package/dist/store/postgres/schema.d.ts +2 -2
- package/dist/store/postgres/schema.js +9 -1
- package/dist/store/postgres/search.js +3 -0
- package/dist/store/postgres/sessions.d.ts +2 -2
- package/dist/store/postgres/sessions.js +9 -2
- package/dist/store/postgres/vectorSearch.js +3 -0
- package/dist/store/project-resolver.d.ts +16 -0
- package/dist/store/project-resolver.js +49 -0
- package/dist/store/project-scope.d.ts +5 -0
- package/dist/store/project-scope.js +16 -0
- package/dist/store/scoped-store.d.ts +3 -0
- package/dist/store/scoped-store.js +49 -0
- package/dist/store/sqlite/filters.d.ts +3 -2
- package/dist/store/sqlite/filters.js +23 -9
- package/dist/store/sqlite/index.d.ts +4 -2
- package/dist/store/sqlite/index.js +7 -0
- package/dist/store/sqlite/observations.js +13 -7
- package/dist/store/sqlite/project-links.d.ts +3 -0
- package/dist/store/sqlite/project-links.js +15 -0
- package/dist/store/sqlite/schema.sql +9 -0
- package/dist/store/sqlite/search.js +5 -0
- package/dist/store/sqlite/sessions.d.ts +2 -2
- package/dist/store/sqlite/sessions.js +8 -2
- package/dist/types.d.ts +4 -3
- package/dist/util/claude-binary.d.ts +15 -1
- package/dist/util/claude-binary.js +39 -7
- package/dist/util/project-key.d.ts +7 -0
- package/dist/util/project-key.js +23 -0
- package/dist/util/remote-key.d.ts +3 -0
- package/dist/util/remote-key.js +50 -0
- package/docs/setup-guide.md +21 -13
- package/package.json +1 -1
- package/skills/catchup/SKILL.md +44 -0
- package/skills/handoff/SKILL.md +62 -0
|
@@ -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:
|
|
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
|
|
32
|
+
WHERE ${scope} AND summary IS NOT NULL
|
|
27
33
|
ORDER BY started_at DESC LIMIT ?`)
|
|
28
|
-
.all(
|
|
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?:
|
|
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?:
|
|
51
|
+
project?: ProjectFilter;
|
|
51
52
|
kind?: ObservationKind;
|
|
52
53
|
before?: number;
|
|
53
54
|
}
|
|
54
55
|
export interface ListFilter {
|
|
55
|
-
project?:
|
|
56
|
+
project?: ProjectFilter;
|
|
56
57
|
sessionId?: string;
|
|
57
58
|
kind?: ObservationKind;
|
|
58
59
|
status?: ObservationStatus;
|
|
@@ -3,7 +3,21 @@ export interface ProcessInfo {
|
|
|
3
3
|
exe: string;
|
|
4
4
|
}
|
|
5
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;
|
|
6
8
|
export declare function findClaudeAncestor(start?: number, inspect?: InspectProcess): string | null;
|
|
7
9
|
export declare function rememberedBinary(file?: string): string | null;
|
|
8
10
|
export declare function rememberClaudeBinary(env?: NodeJS.ProcessEnv, file?: string, find?: () => string | null): void;
|
|
9
|
-
export
|
|
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;
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { execFileSync } from 'node:child_process';
|
|
2
|
-
import { mkdirSync, readFileSync, readlinkSync, statSync, writeFileSync } from 'node:fs';
|
|
3
|
-
import { basename, join } from 'node:path';
|
|
2
|
+
import { accessSync, constants, mkdirSync, readFileSync, readlinkSync, statSync, writeFileSync, } from 'node:fs';
|
|
3
|
+
import { basename, delimiter, isAbsolute, join } from 'node:path';
|
|
4
4
|
import { CONFIG_DIR } from '../config/dir.js';
|
|
5
5
|
const REMEMBERED_FILE = join(CONFIG_DIR, 'claude-binary');
|
|
6
6
|
const MAX_ANCESTORS = 8;
|
|
@@ -15,7 +15,7 @@ function inspectOnLinux(pid) {
|
|
|
15
15
|
return null;
|
|
16
16
|
}
|
|
17
17
|
}
|
|
18
|
-
function inspectWithPs(pid) {
|
|
18
|
+
export function inspectWithPs(pid) {
|
|
19
19
|
try {
|
|
20
20
|
const line = execFileSync('ps', ['-o', 'ppid=,comm=', '-p', String(pid)], {
|
|
21
21
|
encoding: 'utf8',
|
|
@@ -29,7 +29,7 @@ function inspectWithPs(pid) {
|
|
|
29
29
|
return null;
|
|
30
30
|
}
|
|
31
31
|
}
|
|
32
|
-
function inspectProcess(pid) {
|
|
32
|
+
export function inspectProcess(pid) {
|
|
33
33
|
if (process.platform === 'win32')
|
|
34
34
|
return null;
|
|
35
35
|
return process.platform === 'linux' ? inspectOnLinux(pid) : inspectWithPs(pid);
|
|
@@ -44,7 +44,7 @@ export function findClaudeAncestor(start = process.ppid, inspect = inspectProces
|
|
|
44
44
|
if (!info)
|
|
45
45
|
return null;
|
|
46
46
|
if (isClaude(info.exe))
|
|
47
|
-
return info.exe;
|
|
47
|
+
return isAbsolute(info.exe) ? info.exe : null;
|
|
48
48
|
pid = info.parent;
|
|
49
49
|
}
|
|
50
50
|
return null;
|
|
@@ -69,6 +69,38 @@ export function rememberClaudeBinary(env = process.env, file = REMEMBERED_FILE,
|
|
|
69
69
|
}
|
|
70
70
|
catch { }
|
|
71
71
|
}
|
|
72
|
-
export function
|
|
73
|
-
|
|
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';
|
|
74
106
|
}
|
|
@@ -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,50 @@
|
|
|
1
|
+
const REMOTE_NAME = /^[A-Za-z0-9._-]+$/;
|
|
2
|
+
const SCHEME_URL = /^([a-z][a-z0-9+.-]*):\/\/(.+)$/i;
|
|
3
|
+
const SCP_URL = /^(?:[^@/\s]+@)?([^:/\s]+):(?!\/\/)(.+)$/;
|
|
4
|
+
const WINDOWS_PATH = /^[a-z]:[\\/]/i;
|
|
5
|
+
const NETWORK_SCHEMES = new Set(['http', 'https', 'ssh', 'git', 'git+ssh', 'ssh+git']);
|
|
6
|
+
export const DEFAULT_REMOTE = 'origin';
|
|
7
|
+
export function isRemoteName(name) {
|
|
8
|
+
return REMOTE_NAME.test(name);
|
|
9
|
+
}
|
|
10
|
+
function splitAuthority(rest) {
|
|
11
|
+
const slash = rest.indexOf('/');
|
|
12
|
+
return slash === -1
|
|
13
|
+
? { authority: rest, path: '' }
|
|
14
|
+
: { authority: rest.slice(0, slash), path: rest.slice(slash + 1) };
|
|
15
|
+
}
|
|
16
|
+
function hostOf(authority) {
|
|
17
|
+
const withoutUser = authority.slice(authority.lastIndexOf('@') + 1);
|
|
18
|
+
return withoutUser.replace(/:\d*$/, '').toLowerCase();
|
|
19
|
+
}
|
|
20
|
+
function cleanPath(path) {
|
|
21
|
+
return path
|
|
22
|
+
.replace(/[?#].*$/, '')
|
|
23
|
+
.replace(/\/+$/, '')
|
|
24
|
+
.replace(/\.git$/i, '')
|
|
25
|
+
.replace(/\/+$/, '')
|
|
26
|
+
.toLowerCase();
|
|
27
|
+
}
|
|
28
|
+
function join(host, path) {
|
|
29
|
+
const segments = path.split('/').filter((part) => part.length > 0);
|
|
30
|
+
if (host.length === 0 || segments.length < 2 || segments.includes('..'))
|
|
31
|
+
return null;
|
|
32
|
+
return `${host}/${segments.join('/')}`;
|
|
33
|
+
}
|
|
34
|
+
export function normalizeRemote(url) {
|
|
35
|
+
const text = url.trim();
|
|
36
|
+
if (text.length === 0 || WINDOWS_PATH.test(text))
|
|
37
|
+
return null;
|
|
38
|
+
const scheme = SCHEME_URL.exec(text);
|
|
39
|
+
if (scheme) {
|
|
40
|
+
const [, name = '', rest = ''] = scheme;
|
|
41
|
+
if (!NETWORK_SCHEMES.has(name.toLowerCase()))
|
|
42
|
+
return null;
|
|
43
|
+
const { authority, path } = splitAuthority(rest);
|
|
44
|
+
return join(hostOf(authority), cleanPath(path));
|
|
45
|
+
}
|
|
46
|
+
const scp = SCP_URL.exec(text);
|
|
47
|
+
if (scp)
|
|
48
|
+
return join((scp[1] ?? '').toLowerCase(), cleanPath(scp[2] ?? ''));
|
|
49
|
+
return null;
|
|
50
|
+
}
|
package/docs/setup-guide.md
CHANGED
|
@@ -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
|
|
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
|
|
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
|
|
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
|
|
131
|
-
| Read the git history | `claude-db seed --from-git` | Turns your commit history into memory so search has something to match
|
|
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
|
|
133
|
-
|
|
|
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
|
|
266
|
-
|
|
267
|
-
|
|
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 |
|
|
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.
|
|
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._
|