claude-db 0.10.3 → 0.11.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (99) hide show
  1. package/CHANGELOG.md +66 -0
  2. package/README.md +41 -78
  3. package/dist/catchup/gather.d.ts +18 -0
  4. package/dist/catchup/gather.js +46 -0
  5. package/dist/catchup/git-state.d.ts +9 -0
  6. package/dist/catchup/git-state.js +35 -0
  7. package/dist/catchup/render.d.ts +3 -0
  8. package/dist/catchup/render.js +49 -0
  9. package/dist/cli/backfill-output.d.ts +13 -0
  10. package/dist/cli/backfill-output.js +78 -0
  11. package/dist/cli/commands/catchup.d.ts +1 -0
  12. package/dist/cli/commands/catchup.js +14 -0
  13. package/dist/cli/commands/distill.js +13 -2
  14. package/dist/cli/commands/doctor.d.ts +2 -0
  15. package/dist/cli/commands/doctor.js +42 -3
  16. package/dist/cli/commands/insight.js +2 -1
  17. package/dist/cli/commands/setup.js +29 -9
  18. package/dist/cli/files.d.ts +2 -0
  19. package/dist/cli/files.js +15 -1
  20. package/dist/cli/index.js +9 -0
  21. package/dist/cli/install.d.ts +6 -1
  22. package/dist/cli/install.js +11 -20
  23. package/dist/cli/paths.d.ts +1 -1
  24. package/dist/cli/paths.js +2 -2
  25. package/dist/cli/refresh.js +4 -12
  26. package/dist/cli/skills.d.ts +17 -0
  27. package/dist/cli/skills.js +70 -0
  28. package/dist/cli/usage.js +2 -0
  29. package/dist/config/schema.d.ts +3 -0
  30. package/dist/config/schema.js +8 -0
  31. package/dist/context.js +5 -2
  32. package/dist/facts/distill.d.ts +16 -3
  33. package/dist/facts/distill.js +22 -31
  34. package/dist/facts/handoff.d.ts +6 -0
  35. package/dist/facts/handoff.js +35 -0
  36. package/dist/facts/health.d.ts +3 -0
  37. package/dist/facts/health.js +10 -0
  38. package/dist/facts/known.d.ts +4 -0
  39. package/dist/facts/known.js +38 -0
  40. package/dist/facts/model.d.ts +1 -0
  41. package/dist/facts/model.js +12 -0
  42. package/dist/facts/ops.d.ts +1 -1
  43. package/dist/facts/ops.js +4 -2
  44. package/dist/facts/start.js +20 -5
  45. package/dist/store/adapter.d.ts +4 -2
  46. package/dist/store/adapter.js +1 -1
  47. package/dist/store/mongo/docs.d.ts +6 -0
  48. package/dist/store/mongo/filters.d.ts +2 -1
  49. package/dist/store/mongo/filters.js +9 -2
  50. package/dist/store/mongo/index.d.ts +5 -2
  51. package/dist/store/mongo/index.js +13 -2
  52. package/dist/store/mongo/observations.js +9 -5
  53. package/dist/store/mongo/project-links.d.ts +4 -0
  54. package/dist/store/mongo/project-links.js +13 -0
  55. package/dist/store/mongo/search.js +3 -0
  56. package/dist/store/mongo/sessions.d.ts +2 -2
  57. package/dist/store/mongo/sessions.js +5 -1
  58. package/dist/store/mongo/vectorSearch.js +3 -0
  59. package/dist/store/postgres/filters.d.ts +2 -1
  60. package/dist/store/postgres/filters.js +11 -4
  61. package/dist/store/postgres/index.d.ts +4 -2
  62. package/dist/store/postgres/index.js +7 -0
  63. package/dist/store/postgres/observations.js +15 -10
  64. package/dist/store/postgres/project-links.d.ts +3 -0
  65. package/dist/store/postgres/project-links.js +15 -0
  66. package/dist/store/postgres/schema.d.ts +2 -2
  67. package/dist/store/postgres/schema.js +9 -1
  68. package/dist/store/postgres/search.js +3 -0
  69. package/dist/store/postgres/sessions.d.ts +2 -2
  70. package/dist/store/postgres/sessions.js +9 -2
  71. package/dist/store/postgres/vectorSearch.js +3 -0
  72. package/dist/store/project-resolver.d.ts +16 -0
  73. package/dist/store/project-resolver.js +49 -0
  74. package/dist/store/project-scope.d.ts +5 -0
  75. package/dist/store/project-scope.js +16 -0
  76. package/dist/store/scoped-store.d.ts +3 -0
  77. package/dist/store/scoped-store.js +49 -0
  78. package/dist/store/sqlite/filters.d.ts +3 -2
  79. package/dist/store/sqlite/filters.js +23 -9
  80. package/dist/store/sqlite/index.d.ts +4 -2
  81. package/dist/store/sqlite/index.js +7 -0
  82. package/dist/store/sqlite/observations.js +13 -7
  83. package/dist/store/sqlite/project-links.d.ts +3 -0
  84. package/dist/store/sqlite/project-links.js +15 -0
  85. package/dist/store/sqlite/schema.sql +9 -0
  86. package/dist/store/sqlite/search.js +5 -0
  87. package/dist/store/sqlite/sessions.d.ts +2 -2
  88. package/dist/store/sqlite/sessions.js +8 -2
  89. package/dist/types.d.ts +4 -3
  90. package/dist/util/claude-binary.d.ts +15 -1
  91. package/dist/util/claude-binary.js +39 -7
  92. package/dist/util/project-key.d.ts +7 -0
  93. package/dist/util/project-key.js +23 -0
  94. package/dist/util/remote-key.d.ts +3 -0
  95. package/dist/util/remote-key.js +50 -0
  96. package/docs/setup-guide.md +47 -291
  97. package/package.json +2 -2
  98. package/skills/catchup/SKILL.md +46 -0
  99. package/skills/handoff/SKILL.md +78 -0
@@ -3,15 +3,26 @@ import { closeLandedWork, openWork, redact } from '../../capture/index.js';
3
3
  import { CONFIG_PATH } from '../../config/index.js';
4
4
  import { DIST_DIR } from '../constants.js';
5
5
  import { assertStableLocation, install, uninstall } from '../install.js';
6
- import { instructionsPathFor, mcpPathFor, settingsPathFor, skillPathFor } from '../paths.js';
6
+ import { instructionsPathFor, mcpPathFor, settingsPathFor } from '../paths.js';
7
7
  import { createContext } from '../../context.js';
8
8
  import { join, resolve } from 'node:path';
9
9
  import { readFileSync, statSync } from 'node:fs';
10
10
  import { resolveProject } from '../../util/project.js';
11
11
  import { mentionsPath } from '../../util/paths.js';
12
12
  import { transcriptsFor } from '../../capture/index.js';
13
- import { factCounts, pendingSessions } from '../../facts/distill.js';
13
+ import { factCounts, oldestPendingAt, pendingSessions } from '../../facts/distill.js';
14
+ import { distillUsage } from '../../facts/budget.js';
15
+ import { waitingWarning } from '../../facts/health.js';
14
16
  import { pickStatus } from './pick.js';
17
+ function printSkills(results) {
18
+ for (const { name, path, outcome } of results) {
19
+ if (outcome === 'written')
20
+ console.log(`Skill : ${path} (/${name})`);
21
+ if (outcome === 'kept-yours') {
22
+ console.log(`Skill : /${name} not installed, you already have your own at ${path}`);
23
+ }
24
+ }
25
+ }
15
26
  export async function cmdInstall(scope) {
16
27
  const project = resolveProject(undefined);
17
28
  try {
@@ -21,14 +32,14 @@ export async function cmdInstall(scope) {
21
32
  console.error(error instanceof Error ? error.message : String(error));
22
33
  process.exit(1);
23
34
  }
24
- const settingsPath = install(DIST_DIR, scope, project);
35
+ const { settingsPath, skills } = install(DIST_DIR, scope, project);
25
36
  const ctx = await createContext();
26
37
  const embedder = await ctx.embedder();
27
38
  await ctx.close();
28
39
  console.log(`Scope : ${scope === 'project' ? `this project only (${project})` : 'all projects on this machine'}`);
29
40
  console.log(`Settings : ${settingsPath}`);
30
41
  console.log(`Guidance : ${instructionsPathFor(scope, project)}`);
31
- console.log(`Skill : ${skillPathFor(scope, project)} (/cdb-scan)`);
42
+ printSkills(skills);
32
43
  console.log(`Config : ${CONFIG_PATH}`);
33
44
  console.log(`Database : ${redact(ctx.config.database)}`);
34
45
  if (embedder.id === 'builtin-hashing') {
@@ -92,16 +103,25 @@ export async function cmdStatus() {
92
103
  const mcpFile = [mcpPathFor('project', project), mcpPathFor('global', project)].find((candidate) => fileMentions(candidate, resolve(DIST_DIR, 'mcp', 'server.js')));
93
104
  console.log(`mcp : ${mcpFile ? `registered (${mcpFile})` : 'NOT REGISTERED'}`);
94
105
  console.log(`sessions : ${sessions.length} recorded for this project`);
95
- const saved = (await ctx.store.listProjects()).find((entry) => entry.project === project);
96
- const lastSaved = saved?.lastActive ?? 0;
106
+ const names = await ctx.store.projectScope(project);
107
+ const lastSaved = Math.max(0, ...(await ctx.store.listProjects())
108
+ .filter((entry) => names.includes(entry.project))
109
+ .map((entry) => entry.lastActive));
97
110
  const worked = workedAt(project);
98
111
  console.log(`worked : ${worked.last > 0 ? ago(worked.last) : 'never'}`);
99
112
  console.log(`recorded : ${lastSaved > 0 ? ago(lastSaved) : 'never'}`);
100
113
  const facts = await factCounts(ctx, project);
101
114
  console.log(`facts : ${facts.project} for this project, ${facts.you} about you`);
102
- console.log(ctx.config.distill.enabled
103
- ? `waiting : ${(await pendingSessions(ctx, project)).length} chat(s) not yet turned into facts`
104
- : 'distill : off, so chats are not turned into facts (claude-db distill on)');
115
+ if (ctx.config.distill.enabled) {
116
+ const waiting = (await pendingSessions(ctx, project)).length;
117
+ console.log(`waiting : ${waiting} chat(s) not yet turned into facts`);
118
+ const warning = waitingWarning(waiting, await oldestPendingAt(ctx, project), distillUsage());
119
+ if (warning)
120
+ console.log(warning);
121
+ }
122
+ else {
123
+ console.log('distill : off, so chats are not turned into facts (claude-db distill on)');
124
+ }
105
125
  console.log(pickStatus(ctx.config));
106
126
  await closeLandedWork(ctx.store, project);
107
127
  const open = await openWork(ctx.store, project);
@@ -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
+ }
package/dist/cli/index.js CHANGED
@@ -9,6 +9,7 @@ import { cmdForget, cmdRemember, cmdSearch } from './commands/memory.js';
9
9
  import { cmdExport, cmdImport, cmdPrune, cmdReembed } from './commands/transfer.js';
10
10
  import { cmdMerge, cmdProjects, cmdStats } from './commands/insight.js';
11
11
  import { cmdFlush, cmdRedact, cmdReset, cmdUpdate } from './commands/maintain.js';
12
+ import { cmdCatchup } from './commands/catchup.js';
12
13
  import { cmdDistill } from './commands/distill.js';
13
14
  import { cmdPick } from './commands/pick.js';
14
15
  import { cmdScan, cmdUsages } from './commands/graph.js';
@@ -16,6 +17,7 @@ import { cmdSeed } from './commands/seed.js';
16
17
  import { cmdAdoption } from './commands/adoption.js';
17
18
  import { cmdView } from './commands/view.js';
18
19
  import { silenceSqliteWarning } from '../util/warnings.js';
20
+ import { packageVersion } from '../update.js';
19
21
  silenceSqliteWarning();
20
22
  const [command, ...args] = process.argv.slice(2);
21
23
  try {
@@ -75,6 +77,9 @@ async function run() {
75
77
  case 'update':
76
78
  await cmdUpdate(args);
77
79
  break;
80
+ case 'catchup':
81
+ await cmdCatchup();
82
+ break;
78
83
  case 'distill':
79
84
  await cmdDistill(args);
80
85
  break;
@@ -108,6 +113,10 @@ async function run() {
108
113
  case 'sync':
109
114
  await cmdSync(args);
110
115
  break;
116
+ case '--version':
117
+ case '-v':
118
+ console.log(packageVersion());
119
+ break;
111
120
  default:
112
121
  usage();
113
122
  }
@@ -1,6 +1,11 @@
1
1
  import { Scope } from './paths.js';
2
+ import type { SkillInstallResult } from './skills.js';
2
3
  export declare function assertStableLocation(distDir: string): void;
3
4
  export declare function refreshHooks(distDir: string, path: string): boolean;
4
- export declare function install(distDir: string, scope: Scope, project: string): string;
5
+ export interface InstallResult {
6
+ settingsPath: string;
7
+ skills: SkillInstallResult[];
8
+ }
9
+ export declare function install(distDir: string, scope: Scope, project: string): InstallResult;
5
10
  export declare function uninstall(distDir: string, scope: Scope, project: string): string | null;
6
11
  export declare function ourHookFile(command: string): string | null;
@@ -1,20 +1,10 @@
1
- import { instructionsPathFor, mcpPathFor, settingsPathFor, skillPathFor } from './paths.js';
2
- import { dirname, resolve } from 'node:path';
1
+ import { instructionsPathFor, mcpPathFor, settingsPathFor } from './paths.js';
2
+ import { installSkills, removeSkills } from './skills.js';
3
+ import { resolve } from 'node:path';
3
4
  import { execFileSync } from 'node:child_process';
4
- import { readJson, readText, writeAtomic, writeJson } from './files.js';
5
+ import { readJson, writeJson, writeJsonOrRemove } from './files.js';
5
6
  import { removeInstructions, writeInstructions } from './instructions.js';
6
- import { rmSync } from 'node:fs';
7
7
  import { toPosix } from '../util/paths.js';
8
- function writeSkill(distDir, scope, project) {
9
- const source = resolve(distDir, '..', 'skills', 'cdb-scan', 'SKILL.md');
10
- const body = readText(source);
11
- if (body.length > 0)
12
- writeAtomic(skillPathFor(scope, project), body);
13
- }
14
- function removeSkill(scope, project) {
15
- const path = skillPathFor(scope, project);
16
- rmSync(dirname(path), { recursive: true, force: true });
17
- }
18
8
  const HOOKS = [
19
9
  ['SessionStart', 'session-start.js'],
20
10
  ['UserPromptSubmit', 'user-prompt.js'],
@@ -85,16 +75,16 @@ export function install(distDir, scope, project) {
85
75
  writeJson(path, settings);
86
76
  const server = resolve(distDir, 'mcp', 'server.js');
87
77
  writeInstructions(instructionsPathFor(scope, project));
88
- writeSkill(distDir, scope, project);
78
+ const skills = installSkills(distDir, scope, project);
89
79
  if (scope === 'global' && registerViaCli(server))
90
- return path;
80
+ return { settingsPath: path, skills };
91
81
  const mcpPath = mcpPathFor(scope, project);
92
82
  const mcpConfig = readJson(mcpPath);
93
83
  const servers = (mcpConfig['mcpServers'] ?? {});
94
84
  servers['memory'] = { command: 'node', args: [server] };
95
85
  mcpConfig['mcpServers'] = servers;
96
86
  writeJson(mcpPath, mcpConfig);
97
- return path;
87
+ return { settingsPath: path, skills };
98
88
  }
99
89
  function claudeMcp(args) {
100
90
  try {
@@ -114,6 +104,7 @@ export function uninstall(distDir, scope, project) {
114
104
  const settings = readJson(path);
115
105
  if (Object.keys(settings).length === 0)
116
106
  return null;
107
+ const save = scope === 'project' ? writeJsonOrRemove : writeJson;
117
108
  const hooks = (settings['hooks'] ?? {});
118
109
  for (const [event, entries] of Object.entries(hooks)) {
119
110
  const kept = withoutOurHooks(entries);
@@ -126,9 +117,9 @@ export function uninstall(distDir, scope, project) {
126
117
  settings['hooks'] = hooks;
127
118
  else
128
119
  delete settings['hooks'];
129
- writeJson(path, settings);
120
+ save(path, settings);
130
121
  removeInstructions(instructionsPathFor(scope, project));
131
- removeSkill(scope, project);
122
+ removeSkills(scope, project);
132
123
  if (scope === 'global' && claudeMcp(['mcp', 'remove', 'memory', '-s', 'user'])) {
133
124
  return path;
134
125
  }
@@ -142,7 +133,7 @@ export function uninstall(distDir, scope, project) {
142
133
  else
143
134
  delete mcpConfig['mcpServers'];
144
135
  if (existed)
145
- writeJson(mcpPath, mcpConfig);
136
+ save(mcpPath, mcpConfig);
146
137
  return path;
147
138
  }
148
139
  function hookCommand(distDir, file) {
@@ -1,5 +1,5 @@
1
1
  export type Scope = 'global' | 'project';
2
2
  export declare function settingsPathFor(scope: Scope, project: string): string;
3
3
  export declare function instructionsPathFor(scope: Scope, project: string): string;
4
- export declare function skillPathFor(scope: Scope, project: string): string;
4
+ export declare function skillPathFor(scope: Scope, project: string, name?: string): string;
5
5
  export declare function mcpPathFor(scope: Scope, project: string): string;
package/dist/cli/paths.js CHANGED
@@ -10,9 +10,9 @@ export function instructionsPathFor(scope, project) {
10
10
  ? join(project, 'CLAUDE.local.md')
11
11
  : join(homedir(), '.claude', 'CLAUDE.md');
12
12
  }
13
- export function skillPathFor(scope, project) {
13
+ export function skillPathFor(scope, project, name = 'cdb-scan') {
14
14
  const root = scope === 'project' ? join(project, '.claude') : join(homedir(), '.claude');
15
- return join(root, 'skills', 'cdb-scan', 'SKILL.md');
15
+ return join(root, 'skills', name, 'SKILL.md');
16
16
  }
17
17
  export function mcpPathFor(scope, project) {
18
18
  return scope === 'project' ? join(project, '.mcp.json') : join(homedir(), '.claude.json');
@@ -1,23 +1,15 @@
1
1
  import { BLOCK_START, INSTRUCTIONS, writeInstructions } from './instructions.js';
2
2
  import { refreshHooks } from './install.js';
3
- import { instructionsPathFor, settingsPathFor, skillPathFor } from './paths.js';
4
- import { readText, writeAtomic } from './files.js';
5
- import { resolve } from 'node:path';
3
+ import { instructionsPathFor, settingsPathFor } from './paths.js';
4
+ import { readText } from './files.js';
5
+ import { refreshSkills } from './skills.js';
6
6
  export function refreshInstalled(distDir, project) {
7
7
  const refreshed = [];
8
8
  for (const scope of ['project', 'global']) {
9
9
  const settingsPath = settingsPathFor(scope, project);
10
10
  if (refreshHooks(distDir, settingsPath))
11
11
  refreshed.push(settingsPath);
12
- const skillPath = skillPathFor(scope, project);
13
- const current = readText(skillPath);
14
- if (current.length > 0) {
15
- const packaged = readText(resolve(distDir, '..', 'skills', 'cdb-scan', 'SKILL.md'));
16
- if (packaged.length > 0 && packaged !== current) {
17
- writeAtomic(skillPath, packaged);
18
- refreshed.push(skillPath);
19
- }
20
- }
12
+ refreshed.push(...refreshSkills(distDir, scope, project));
21
13
  const instructionsPath = instructionsPathFor(scope, project);
22
14
  const existing = readText(instructionsPath);
23
15
  if (existing.includes(BLOCK_START) && !existing.includes(INSTRUCTIONS)) {
@@ -0,0 +1,17 @@
1
+ import type { Scope } from './paths.js';
2
+ export declare const SKILL_MARKER = "Shipped with claude-db.";
3
+ export interface SkillSpec {
4
+ name: string;
5
+ claimsExisting: boolean;
6
+ }
7
+ export declare const SKILLS: readonly SkillSpec[];
8
+ export type SkillInstallOutcome = 'written' | 'kept-yours' | 'missing-source';
9
+ export interface SkillInstallResult {
10
+ name: string;
11
+ path: string;
12
+ outcome: SkillInstallOutcome;
13
+ }
14
+ export declare function installSkills(distDir: string, scope: Scope, project: string): SkillInstallResult[];
15
+ export declare function refreshSkills(distDir: string, scope: Scope, project: string): string[];
16
+ export declare function removeSkills(scope: Scope, project: string): void;
17
+ export declare function describeSkills(project: string): string;
@@ -0,0 +1,70 @@
1
+ import { rmSync } from 'node:fs';
2
+ import { dirname, resolve } from 'node:path';
3
+ import { readText, removeIfEmpty, writeAtomic } from './files.js';
4
+ import { skillPathFor } from './paths.js';
5
+ export const SKILL_MARKER = 'Shipped with claude-db.';
6
+ export const SKILLS = [
7
+ { name: 'cdb-scan', claimsExisting: true },
8
+ { name: 'catchup', claimsExisting: false },
9
+ { name: 'handoff', claimsExisting: false },
10
+ ];
11
+ function packagedBody(distDir, spec) {
12
+ return readText(resolve(distDir, '..', 'skills', spec.name, 'SKILL.md'));
13
+ }
14
+ function isOurs(spec, installedBody) {
15
+ return spec.claimsExisting || installedBody.includes(SKILL_MARKER);
16
+ }
17
+ export function installSkills(distDir, scope, project) {
18
+ return SKILLS.map((spec) => {
19
+ const path = skillPathFor(scope, project, spec.name);
20
+ const body = packagedBody(distDir, spec);
21
+ if (body.length === 0)
22
+ return { name: spec.name, path, outcome: 'missing-source' };
23
+ const installed = readText(path);
24
+ if (installed.length > 0 && !isOurs(spec, installed)) {
25
+ return { name: spec.name, path, outcome: 'kept-yours' };
26
+ }
27
+ writeAtomic(path, body);
28
+ return { name: spec.name, path, outcome: 'written' };
29
+ });
30
+ }
31
+ export function refreshSkills(distDir, scope, project) {
32
+ const installedHere = SKILLS.some((spec) => readText(skillPathFor(scope, project, spec.name)).length > 0);
33
+ if (!installedHere)
34
+ return [];
35
+ const refreshed = [];
36
+ for (const spec of SKILLS) {
37
+ const path = skillPathFor(scope, project, spec.name);
38
+ const installed = readText(path);
39
+ const body = packagedBody(distDir, spec);
40
+ const foreign = installed.length > 0 && !isOurs(spec, installed);
41
+ if (body.length === 0 || foreign || body === installed)
42
+ continue;
43
+ writeAtomic(path, body);
44
+ refreshed.push(path);
45
+ }
46
+ return refreshed;
47
+ }
48
+ export function removeSkills(scope, project) {
49
+ for (const spec of SKILLS) {
50
+ const path = skillPathFor(scope, project, spec.name);
51
+ if (!isOurs(spec, readText(path)))
52
+ continue;
53
+ rmSync(dirname(path), { recursive: true, force: true });
54
+ }
55
+ if (scope !== 'project')
56
+ return;
57
+ const skillsDir = dirname(dirname(skillPathFor(scope, project)));
58
+ removeIfEmpty(skillsDir);
59
+ removeIfEmpty(dirname(skillsDir));
60
+ }
61
+ export function describeSkills(project) {
62
+ const scopes = ['project', 'global'];
63
+ const parts = SKILLS.map((spec) => {
64
+ const found = scopes.some((scope) => readText(skillPathFor(scope, project, spec.name)).length > 0);
65
+ return found ? `/${spec.name} ok` : `/${spec.name} MISSING`;
66
+ });
67
+ const missing = parts.some((part) => part.endsWith('MISSING'));
68
+ const line = `skills : ${parts.join(', ')}`;
69
+ return missing ? `${line}\n fix with: claude-db install` : line;
70
+ }
package/dist/cli/usage.js CHANGED
@@ -16,6 +16,7 @@ export function usage() {
16
16
  projects List every project with memory in this database
17
17
  merge [<old-path>] [--yes] Move memory from an old project path onto this one
18
18
  stats What this project's memory is made of
19
+ catchup Where did I stop: last chat, to-dos, git state, last handoff
19
20
  adoption How often sessions grep vs use the memory tools
20
21
  view [--export <file>] See this project's memory live in the browser
21
22
  distill [on|off] Turn chats into facts with Haiku; no argument shows status
@@ -35,6 +36,7 @@ export function usage() {
35
36
  reembed [--project] Re-embed with the current model
36
37
  prune --older-than <days> Delete old memory (dry run without --yes)
37
38
  reset [--project] --yes Delete stored memory (dry run without --yes)
39
+ --version, -v Print the installed version
38
40
 
39
41
  --project scope to the current repo via .claude/settings.local.json
40
42
  instead of every project on this machine
@@ -17,6 +17,9 @@ export declare const ConfigSchema: z.ZodObject<{
17
17
  notify: "notify";
18
18
  off: "off";
19
19
  }>>;
20
+ project: z.ZodPrefault<z.ZodObject<{
21
+ remote: z.ZodDefault<z.ZodString>;
22
+ }, z.core.$strip>>;
20
23
  capture: z.ZodPrefault<z.ZodObject<{
21
24
  tools: z.ZodDefault<z.ZodArray<z.ZodString>>;
22
25
  exclude: z.ZodDefault<z.ZodArray<z.ZodString>>;
@@ -10,6 +10,14 @@ export const ConfigSchema = z.object({
10
10
  })
11
11
  .prefault({}),
12
12
  updates: z.enum(['auto', 'notify', 'off']).default('notify'),
13
+ project: z
14
+ .object({
15
+ remote: z
16
+ .string()
17
+ .regex(/^[A-Za-z0-9._-]+$/)
18
+ .default('origin'),
19
+ })
20
+ .prefault({}),
13
21
  capture: z
14
22
  .object({
15
23
  tools: z.array(z.string()).default(['Edit', 'Write', 'Bash', 'NotebookEdit']),
package/dist/context.js CHANGED
@@ -2,10 +2,13 @@ import { loadConfig } from './config/index.js';
2
2
  import { createEmbedder, NoopEmbedder } from './embed/index.js';
3
3
  import { SearchService } from './search/index.js';
4
4
  import { createStore } from './store/index.js';
5
+ import { createScopeResolver } from './store/project-resolver.js';
6
+ import { withProjectScope } from './store/scoped-store.js';
5
7
  export async function createContext(overrides) {
6
8
  const config = { ...loadConfig(), ...overrides };
7
- const store = await createStore(config.database);
8
- await store.init();
9
+ const raw = await createStore(config.database);
10
+ await raw.init();
11
+ const store = withProjectScope(raw, createScopeResolver({ store: raw, remote: config.project.remote }));
9
12
  let pending = null;
10
13
  const embedder = () => {
11
14
  pending ??= withTimeout(createEmbedder(config.embeddings.provider).catch(() => new NoopEmbedder()), config.embeddings.timeoutMs);
@@ -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';
@@ -10,15 +9,29 @@ export interface DistillResult {
10
9
  set: number;
11
10
  retired: number;
12
11
  }
12
+ export type BackfillStep = {
13
+ kind: 'begin';
14
+ total: number;
15
+ } | {
16
+ kind: 'start';
17
+ index: number;
18
+ total: number;
19
+ } | {
20
+ kind: 'done';
21
+ index: number;
22
+ total: number;
23
+ facts: number;
24
+ };
13
25
  export interface BackfillResult {
14
26
  distilled: number;
27
+ facts: number;
15
28
  remaining: number;
16
29
  stopped: 'done' | 'over-budget' | 'failed';
17
30
  }
18
31
  export declare function distillSession(ctx: RecallContext, project: string, sessionId: string, run?: Runner): Promise<DistillResult>;
19
32
  export declare function pendingSessions(ctx: RecallContext, project: string, now?: number): Promise<string[]>;
20
- export declare function backfill(ctx: RecallContext, project: string, run?: Runner): Promise<BackfillResult>;
21
- export declare function existingFacts(ctx: RecallContext, project: string): Promise<ExistingFact[]>;
33
+ export declare function oldestPendingAt(ctx: RecallContext, project: string, now?: number): Promise<number | null>;
34
+ export declare function backfill(ctx: RecallContext, project: string, run?: Runner, onStep?: (step: BackfillStep) => void): Promise<BackfillResult>;
22
35
  export declare function chatWindows(rows: Observation[], most?: number): string[];
23
36
  export declare function factCounts(ctx: RecallContext, project: string): Promise<{
24
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, 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);
@@ -65,46 +66,36 @@ async function distillWindow(ctx, project, chat, source, at, run) {
65
66
  const retired = await ctx.store.markReplaced(retiring);
66
67
  return { ok: true, set: facts.length, retired, texts: sets.map((op) => op.text) };
67
68
  }
68
- export async function pendingSessions(ctx, project, now = Date.now()) {
69
+ async function pendingChats(ctx, project, now) {
69
70
  const cutoff = now - ctx.config.distill.backfillDays * DAY_MS;
70
71
  return (await ctx.store.recentSessions(project, 1000))
71
72
  .filter((session) => session.distilledAt === undefined && session.startedAt >= cutoff)
72
- .map((session) => session.id);
73
+ .map((session) => ({ id: session.id, startedAt: session.startedAt }));
74
+ }
75
+ export async function pendingSessions(ctx, project, now = Date.now()) {
76
+ return (await pendingChats(ctx, project, now)).map((chat) => chat.id);
77
+ }
78
+ export async function oldestPendingAt(ctx, project, now = Date.now()) {
79
+ const chats = await pendingChats(ctx, project, now);
80
+ return chats.length === 0 ? null : Math.min(...chats.map((chat) => chat.startedAt));
73
81
  }
74
- export async function backfill(ctx, project, run = runHeadlessResult) {
82
+ export async function backfill(ctx, project, run = runHeadlessResult, onStep = () => { }) {
75
83
  const pending = await pendingSessions(ctx, project);
84
+ const total = pending.length;
85
+ onStep({ kind: 'begin', total });
76
86
  let distilled = 0;
87
+ let facts = 0;
77
88
  for (const [index, sessionId] of pending.entries()) {
89
+ onStep({ kind: 'start', index: index + 1, total });
78
90
  const result = await distillSession(ctx, project, sessionId, run);
79
91
  if (result.outcome === 'over-budget' || result.outcome === 'failed') {
80
- return { distilled, remaining: pending.length - index, stopped: result.outcome };
92
+ return { distilled, facts, remaining: total - index, stopped: result.outcome };
81
93
  }
82
94
  distilled += 1;
95
+ facts += result.set;
96
+ onStep({ kind: 'done', index: index + 1, total, facts });
83
97
  }
84
- return { distilled, remaining: 0, stopped: 'done' };
85
- }
86
- export async function existingFacts(ctx, project) {
87
- const owners = [
88
- [project, 'project'],
89
- [youScope(), 'you'],
90
- ];
91
- const facts = [];
92
- for (const [owner, scope] of owners) {
93
- const rows = await ctx.store.list({
94
- project: owner,
95
- sessionId: FACT_SESSION,
96
- newest: true,
97
- limit: EXISTING_LIMIT,
98
- });
99
- for (const obs of rows) {
100
- const key = factKey(obs);
101
- const type = factType(obs);
102
- if (obs.status === 'replaced' || !key || !type)
103
- continue;
104
- facts.push({ key, type, scope, text: obs.title });
105
- }
106
- }
107
- return facts;
98
+ return { distilled, facts, remaining: 0, stopped: 'done' };
108
99
  }
109
100
  export function chatWindows(rows, most = MAX_WINDOWS) {
110
101
  const windows = [];
@@ -0,0 +1,6 @@
1
+ import type { RecallContext } from '../context.js';
2
+ import type { Observation } from '../types.js';
3
+ export declare const HANDOFF_TAG = "handoff";
4
+ export declare const HANDOFF_KEY = "handoff";
5
+ export declare function newestHandoff(ctx: RecallContext, project: string, now?: number): Promise<Observation | null>;
6
+ export declare function handoffBodyLines(obs: Observation): string[];
@@ -0,0 +1,35 @@
1
+ import { MANUAL_SESSION } from './render.js';
2
+ export const HANDOFF_TAG = 'handoff';
3
+ export const HANDOFF_KEY = 'handoff';
4
+ const DAY_MS = 24 * 60 * 60 * 1000;
5
+ const HANDOFF_MAX_AGE_MS = 14 * DAY_MS;
6
+ const MANUAL_NOTES_SCANNED = 50;
7
+ const HANDOFF_MAX_LINES = 8;
8
+ const HANDOFF_LINE_CHARS = 220;
9
+ export async function newestHandoff(ctx, project, now = Date.now()) {
10
+ const notes = await ctx.store.list({
11
+ project,
12
+ sessionId: MANUAL_SESSION,
13
+ newest: true,
14
+ limit: MANUAL_NOTES_SCANNED,
15
+ });
16
+ const current = (obs) => obs.status !== 'replaced' &&
17
+ obs.tags.includes(HANDOFF_TAG) &&
18
+ now - obs.createdAt <= HANDOFF_MAX_AGE_MS;
19
+ return notes.find(current) ?? null;
20
+ }
21
+ function clipLine(line) {
22
+ return line.length > HANDOFF_LINE_CHARS
23
+ ? `${line.slice(0, HANDOFF_LINE_CHARS - 1).trimEnd()}…`
24
+ : line;
25
+ }
26
+ export function handoffBodyLines(obs) {
27
+ const lines = obs.body
28
+ .split('\n')
29
+ .slice(1)
30
+ .map((line) => line.trimEnd())
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;
35
+ }
@@ -0,0 +1,3 @@
1
+ import type { BudgetUsage } from '../util/daily-budget.js';
2
+ export declare const STALE_WAITING_MS: number;
3
+ export declare function waitingWarning(waiting: number, oldestAt: number | null, usage: BudgetUsage, now?: number): string | null;
@@ -0,0 +1,10 @@
1
+ export const STALE_WAITING_MS = 24 * 60 * 60 * 1000;
2
+ export function waitingWarning(waiting, oldestAt, usage, now = Date.now()) {
3
+ if (waiting === 0 || oldestAt === null)
4
+ return null;
5
+ if (now - oldestAt < STALE_WAITING_MS)
6
+ return null;
7
+ if (usage.used > 0 || usage.pausedUntil > now)
8
+ return null;
9
+ return `warning : ${waiting} chat(s) have waited over a day and no facts were tried today. Run claude-db doctor`;
10
+ }
@@ -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[]>;