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
package/CHANGELOG.md CHANGED
@@ -1,5 +1,71 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.11.1
4
+
5
+ ### Fixed
6
+
7
+ - **Facts no longer repeat a rule you saved by hand.** When a chat ended, the fact-making call saw the
8
+ earlier facts but not the rules you saved with `remember`, so it saved the same rule again and the start
9
+ of a chat listed it twice. The call now sees those rules and is told not to repeat them. Rules already
10
+ duplicated stay until you remove one with `claude-db forget <id>`.
11
+ - **`uninstall --project` leaves nothing empty behind.** It used to leave an empty `.mcp.json` and
12
+ `.claude/settings.local.json`, and an empty `.claude/skills` folder. It now removes them when nothing else
13
+ is in them. Your own settings, servers and skills are never touched, and a machine-wide uninstall is
14
+ unchanged.
15
+
16
+ ### Changed
17
+
18
+ - **`/handoff` keeps more, in a fixed size.** The note can now hold Decided, Rejected, Watch out and State
19
+ lines, with the reason after "because", and carries still-true lines forward. It is capped at 8 lines of
20
+ about 200 characters. At the start of a chat only those 8 lines are shown, each cut at 220 characters, with
21
+ a line saying how many more there are. The first line ends with the note's id, so the full text can be
22
+ read with `get_observations`.
23
+ - **`/catchup` shows the branch and how many files are uncommitted**, and the recent decisions and dead
24
+ ends, so a handoff can be written from facts and not only from the chat.
25
+
26
+ ### Docs
27
+
28
+ - A shorter setup guide and README, and a cleaner docs site with a Skills page and a clearer code block.
29
+
30
+ ## 0.11.0
31
+
32
+ ### Added
33
+
34
+ - **Projects are matched by git remote.** A repository with an `origin` remote is now one project wherever
35
+ it is cloned, so a laptop and a Mac share memory when they use the same Postgres or MongoDB database.
36
+ The `ssh` and `https` addresses of one repository match. Any token in the address is dropped and never
37
+ stored. A folder with no remote is matched by its path, as before. A fork has its own remote, so it is
38
+ its own project. The new setting `project.remote` picks another remote than `origin`. Memory saved before
39
+ this, under a folder path, is still found and is not moved. A second machine needs this version to share
40
+ notes by remote. A machine still on 0.10.x keeps working on the same database but does not see notes
41
+ saved by remote, so update every machine that shares a database. Each folder links itself to its remote
42
+ the first time you use 0.11.0 in it, and notes saved under that folder's path are found by other machines
43
+ from then on. Postgres moves to schema version 5 on first use and adds one table, `project_links`.
44
+ MongoDB gets the same collection.
45
+ - **`/catchup` and `/handoff` skills.** `/catchup` says where you stopped, in three groups: done, open and
46
+ next, from the last chat, the recorded to-dos, the last handoff and git. `/handoff` writes the same three
47
+ lines, saves them as the project's current handoff, and prints them. The next chat sees the handoff at the
48
+ start for 14 days. `claude-db catchup` prints the facts both skills use. If you already have a skill with
49
+ one of these names, claude-db keeps yours and says so.
50
+ - **`claude-db --version` and `-v`.**
51
+ - **`doctor` shows which `claude` it found and where from**, for example `from saved path`. With no
52
+ `claude` it says so and how to fix it. `doctor --deep` also makes one small real Haiku call. `doctor` lists
53
+ the installed skills.
54
+ - **`status` warns when chats have waited over a day** and no fact-making call was tried.
55
+
56
+ ### Changed
57
+
58
+ - **`distill --backfill` shows progress.** It says how many chats are waiting, shows a spinner on a terminal,
59
+ prints one line per finished chat, and ends with the reason if it stops. A pipe or a file gets plain lines.
60
+ - **A session start shows the newest handoff** with its done, open and next lines.
61
+ - **`status` and `projects` count notes saved by another clone** of the same repository as this project's.
62
+ A fact saved by two clones is shown once.
63
+
64
+ ### Fixed
65
+
66
+ - On macOS, a `claude` found by name only could be saved as the useless path `claude`. A bare name is now
67
+ left to the `PATH` search.
68
+
3
69
  ## 0.10.3
4
70
 
5
71
  ### Fixed
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  <img src="./assets/wordmark.svg" alt="claude-db" width="330">
2
2
 
3
- **Persistent memory for Claude Code. Bring your own database.**
3
+ **Free, open-source memory for Claude Code. Your own database, no cloud, no subscription.**
4
4
 
5
5
  [![npm](https://img.shields.io/npm/v/claude-db.svg)](https://www.npmjs.com/package/claude-db)
6
6
  [![CI](https://github.com/Avijit07x/claude-db/actions/workflows/ci.yml/badge.svg)](https://github.com/Avijit07x/claude-db/actions/workflows/ci.yml)
@@ -12,111 +12,74 @@
12
12
 
13
13
  ---
14
14
 
15
- ## Every session starts from zero
15
+ ## Why
16
16
 
17
- You spent an hour yesterday explaining why the store has three adapters, which
18
- approach you tried and dropped, and why one function must not be touched. Today
19
- Claude knows none of it, so you explain it again.
17
+ Every Claude Code chat starts from zero. You explain the same decisions, dead
18
+ ends and rules again, and Claude works out what calls what from scratch.
20
19
 
21
- claude-db gives Claude a memory that lasts, and a map of your code so it stops
22
- working out what calls what from scratch.
20
+ claude-db fixes that. It keeps what you decided and a map of your code, and
21
+ gives Claude the right part of it at the right time.
23
22
 
24
- ## What you get
23
+ ## What it does
25
24
 
26
- - **A memory that carries over.** When a chat ends, its decisions, dead ends and
27
- rules are saved as short facts, and the next chat starts by seeing them.
28
- - **The right memory with each prompt.** Claude Haiku picks the one or two
29
- earlier memories that fit what you just asked. That costs about 20 tokens a
30
- prompt on average, and nothing on 69% of prompts.
31
- - **A code graph.** Who defines or calls a symbol, answered in one call: 2.0x
32
- cheaper than grep and reading files, measured on eight real symbols.
33
- - **Your own database.** SQLite by default, or Postgres or MongoDB to share
34
- memory across machines. No cloud, no subscription.
25
+ - **Remembers across chats.** Decisions, dead ends and rules are saved when a
26
+ chat ends, and the next chat starts by seeing them.
27
+ - **Recalls what fits.** Each prompt gets the one or two earlier memories that
28
+ match it, and nothing when none fit.
29
+ - **Maps your code.** Who defines or calls a symbol is answered in one call,
30
+ instead of grep and reading files.
31
+ - **Keeps it yours.** SQLite on your machine by default, or Postgres or MongoDB
32
+ to share across machines. No cloud, no subscription.
35
33
 
36
34
  ## Install
37
35
 
36
+ You need Node 22.16 or newer and a git repository.
37
+
38
38
  ```bash
39
39
  npm install -g claude-db
40
-
41
40
  cd your-project
42
41
  claude-db install --project
43
42
  ```
44
43
 
45
- Restart Claude Code. Capture and recall are hooks, so there is nothing else to
46
- run.
47
-
48
- `--project` limits it to this repo instead of every project on the machine. Add
49
- `.mcp.json` to your `.gitignore`, since it holds a path that only exists on your
50
- machine.
51
-
52
- A fresh install has no history yet. `claude-db scan` builds the code graph, and
53
- the `/cdb-scan` skill maps an existing codebase into memory, so search has
54
- something to find on day one. The [setup guide](./docs/setup-guide.md) covers
55
- the settings and habits that give the best results.
56
-
57
- ## Commands
58
-
59
- `cdb` is a shorter alias for all of them.
44
+ Restart Claude Code. There is nothing else to run, because capture and recall
45
+ are hooks.
60
46
 
61
- | Command | What it does |
62
- | ------------------------------- | ----------------------------------------------------- |
63
- | `claude-db install [--project]` | Register the hooks and the MCP server |
64
- | `claude-db status` | Is it wired up, and when did it last record anything |
65
- | `claude-db doctor [--deep]` | Show the resolved config; `--deep` tests a round trip |
66
- | `claude-db scan` | Build the code graph for this repo |
67
- | `claude-db use <url>` | Switch database and verify it |
68
- | `claude-db distill [on\|off]` | Turn chats into facts with Haiku |
69
- | `claude-db pick [on\|off]` | Let Haiku pick the memory shown with each prompt |
70
- | `claude-db view` | See this project's memory in the browser |
47
+ Then load what already exists with `claude-db flush` and `claude-db scan`. The
48
+ [setup guide](./docs/setup-guide.md) has the rest.
71
49
 
72
- Every other command, including `search`, `remember`, `sync` and `export`, is in
73
- the [CLI reference](https://claude-db.vercel.app/docs/cli).
50
+ ## Everyday use
74
51
 
75
- ## Use another database
52
+ | Where | What it does |
53
+ | --------------------- | ------------------------------------------------- |
54
+ | `/catchup` | Answers "where did I stop?" when you come back |
55
+ | `/handoff` | Leaves a short note for the next chat or a mate |
56
+ | `/cdb-scan` | Maps an existing codebase into memory |
57
+ | `claude-db status` | Shows whether it is wired up and what it recorded |
58
+ | `claude-db doctor` | Checks the setup, and finds what is wrong |
59
+ | `claude-db use <url>` | Switches to Postgres or MongoDB (`pg`/`mongodb`) |
76
60
 
77
- ```bash
78
- claude-db use "postgres://user:pass@host:5432/memory"
79
- claude-db use "mongodb+srv://user:pass@cluster.mongodb.net/memory"
80
- ```
81
-
82
- Install the driver first, with `npm install -g pg` or `npm install -g mongodb`.
83
- Neither ships by default.
61
+ `cdb` is a shorter alias. Every command is in the
62
+ [CLI reference](https://claude-db.vercel.app/docs/cli).
84
63
 
85
64
  ## Privacy
86
65
 
87
- Memory stays in your own database. Three things use the network, and each has
88
- an off switch:
89
-
90
- - **When a chat ends**, its saved, redacted text is sent once to Claude Haiku
91
- through your own login, to make facts. Turn it off with `claude-db distill off`.
92
- - **When a prompt has related memory**, the prompt, the end of Claude's last
93
- reply and up to ten saved excerpts go to Haiku, so it can pick what to show.
94
- Turn it off with `claude-db pick off`.
95
- - **Once a day**, the npm registry is asked for the latest version. Turn it off
96
- with `"updates": "off"` in the config.
66
+ Memory stays in your own database. Two features call Claude Haiku through your
67
+ own login, and each has an off switch: `claude-db distill off` for making facts
68
+ from finished chats, and `claude-db pick off` for choosing memory per prompt.
69
+ Once a day it asks npm for the latest version (`"updates": "off"` stops that).
97
70
 
98
71
  `.env`, `secrets/`, `node_modules` and `.git/` are never stored. Text inside
99
72
  `<private>...</private>` is stripped, and API keys and tokens are redacted
100
73
  before anything is written or sent.
101
74
 
102
- ## Requirements
103
-
104
- Node 22.16 or newer. SQLite comes from Node's builtin `node:sqlite`, so nothing
105
- compiles at install time. For real semantic search, run
106
- `npm install -g @xenova/transformers` and the embedder upgrades itself.
107
-
108
75
  ## Documentation
109
76
 
110
- - [Documentation site](https://claude-db.vercel.app/docs): the
111
- [CLI reference](https://claude-db.vercel.app/docs/cli),
112
- [MCP tools](https://claude-db.vercel.app/docs/mcp-tools),
113
- [how it works](https://claude-db.vercel.app/docs/how-it-works),
114
- [databases](https://claude-db.vercel.app/docs/databases) and
115
- [troubleshooting](https://claude-db.vercel.app/docs/troubleshooting)
116
- - [Setup guide](./docs/setup-guide.md): settings, habits and costs
77
+ - [Setup guide](./docs/setup-guide.md): install, head start and habits
78
+ - [Documentation site](https://claude-db.vercel.app/docs): CLI, MCP tools,
79
+ databases and troubleshooting
117
80
  - [With and without](./docs/with-and-without.md) and
118
- [benchmarks](https://claude-db.vercel.app/docs/benchmarks): every number,
119
- including the symbols where plain grep wins
81
+ [benchmarks](https://claude-db.vercel.app/docs/benchmarks): the numbers,
82
+ including where plain grep wins
120
83
  - [Changelog](./CHANGELOG.md)
121
84
 
122
85
  ## Contributing
@@ -0,0 +1,18 @@
1
+ import type { RecallContext } from '../context.js';
2
+ import type { GitState } from './git-state.js';
3
+ export interface CatchupData {
4
+ handoff: {
5
+ at: number;
6
+ lines: string[];
7
+ } | null;
8
+ lastChat: {
9
+ at: number;
10
+ summary: string;
11
+ work: string[];
12
+ } | null;
13
+ todos: string[];
14
+ decisions: string[];
15
+ uncommitted: string[];
16
+ git: GitState | null;
17
+ }
18
+ export declare function gatherCatchup(ctx: RecallContext, project: string, now?: number): Promise<CatchupData>;
@@ -0,0 +1,46 @@
1
+ import { openWork } from '../capture/progress.js';
2
+ import { FACT_SESSION, factLabel, factType, onePerKey } from '../facts/model.js';
3
+ import { handoffBodyLines, newestHandoff } from '../facts/handoff.js';
4
+ import { readGitState } from './git-state.js';
5
+ const CHAT_TITLES = 6;
6
+ const TODOS = 5;
7
+ const UNCOMMITTED = 5;
8
+ const DECISIONS = 5;
9
+ const FACTS_SCANNED = 100;
10
+ export async function gatherCatchup(ctx, project, now = Date.now()) {
11
+ const handoff = await newestHandoff(ctx, project, now);
12
+ const [latest] = await ctx.store.recentSessions(project, 1);
13
+ const chatWork = latest
14
+ ? (await ctx.store.list({ project, sessionId: latest.id, newest: true, limit: CHAT_TITLES }))
15
+ .filter((obs) => obs.status !== 'replaced')
16
+ .map((obs) => obs.title)
17
+ : [];
18
+ const facts = await ctx.store.list({
19
+ project,
20
+ sessionId: FACT_SESSION,
21
+ newest: true,
22
+ limit: FACTS_SCANNED,
23
+ });
24
+ const current = onePerKey(facts.filter((obs) => obs.status !== 'replaced'));
25
+ const todos = current
26
+ .filter((obs) => factType(obs) === 'todo')
27
+ .slice(0, TODOS)
28
+ .map((obs) => obs.title);
29
+ const decisions = current
30
+ .filter((obs) => ['decision', 'deadend'].includes(factType(obs) ?? ''))
31
+ .slice(0, DECISIONS)
32
+ .map((obs) => `${factLabel(obs)}: ${obs.title}`);
33
+ const uncommitted = (await openWork(ctx.store, project))
34
+ .slice(0, UNCOMMITTED)
35
+ .map((obs) => obs.title);
36
+ return {
37
+ handoff: handoff ? { at: handoff.createdAt, lines: handoffBodyLines(handoff) } : null,
38
+ lastChat: latest
39
+ ? { at: latest.startedAt, summary: latest.summary ?? '', work: chatWork }
40
+ : null,
41
+ todos,
42
+ decisions,
43
+ uncommitted,
44
+ git: readGitState(project),
45
+ };
46
+ }
@@ -0,0 +1,9 @@
1
+ export interface GitState {
2
+ branch: string | null;
3
+ changed: number;
4
+ status: string[];
5
+ hiddenStatusLines: number;
6
+ commits: string[];
7
+ }
8
+ export type GitRunner = (args: string[]) => string;
9
+ export declare function readGitState(project: string, git?: GitRunner): GitState | null;
@@ -0,0 +1,35 @@
1
+ import { execFileSync } from 'node:child_process';
2
+ import { redact } from '../capture/redact.js';
3
+ const GIT_TIMEOUT_MS = 5000;
4
+ const STATUS_LINES = 15;
5
+ const RECENT_COMMITS = 5;
6
+ function runGit(project) {
7
+ return (args) => execFileSync('git', ['-C', project, ...args], {
8
+ encoding: 'utf8',
9
+ stdio: ['ignore', 'pipe', 'ignore'],
10
+ timeout: GIT_TIMEOUT_MS,
11
+ });
12
+ }
13
+ function lines(text) {
14
+ return text
15
+ .split('\n')
16
+ .map((line) => line.trimEnd())
17
+ .filter((line) => line.length > 0);
18
+ }
19
+ export function readGitState(project, git = runGit(project)) {
20
+ try {
21
+ const status = lines(git(['status', '--short']));
22
+ const branch = lines(git(['branch', '--show-current']))[0] ?? null;
23
+ const commits = lines(git(['log', `-n${RECENT_COMMITS}`, '--pretty=format:%h %s'])).map(redact);
24
+ return {
25
+ branch,
26
+ changed: status.length,
27
+ status: status.slice(0, STATUS_LINES),
28
+ hiddenStatusLines: Math.max(0, status.length - STATUS_LINES),
29
+ commits,
30
+ };
31
+ }
32
+ catch {
33
+ return null;
34
+ }
35
+ }
@@ -0,0 +1,3 @@
1
+ import type { CatchupData } from './gather.js';
2
+ export declare const NOTHING_RECORDED = "Nothing recorded for this project yet.";
3
+ export declare function renderCatchup(data: CatchupData, now?: number): string;
@@ -0,0 +1,49 @@
1
+ import { formatDay } from '../util/day.js';
2
+ export const NOTHING_RECORDED = 'Nothing recorded for this project yet.';
3
+ function section(heading, lines) {
4
+ return lines.length === 0 ? [] : [heading, ...lines, ''];
5
+ }
6
+ function bullets(items) {
7
+ return items.map((item) => ` - ${item}`);
8
+ }
9
+ function gitLines(data) {
10
+ const git = data.git;
11
+ if (!git)
12
+ return { status: [], commits: [] };
13
+ const hidden = git.hiddenStatusLines > 0 ? [` ...and ${git.hiddenStatusLines} more`] : [];
14
+ return {
15
+ status: [...git.status.map((line) => ` ${line}`), ...hidden],
16
+ commits: git.commits.map((line) => ` ${line}`),
17
+ };
18
+ }
19
+ function branchLine(git) {
20
+ if (!git)
21
+ return [];
22
+ const state = git.changed === 0 ? 'clean' : `${git.changed} file${git.changed === 1 ? '' : 's'} uncommitted`;
23
+ return [`Branch: ${git.branch ?? 'detached HEAD'}, ${state}`, ''];
24
+ }
25
+ function chatBlock(chat, now) {
26
+ if (!chat)
27
+ return [];
28
+ const heading = `Last chat (${formatDay(chat.at, now)}): ${chat.summary || 'no summary'}`;
29
+ return [heading, ...bullets(chat.work), ''];
30
+ }
31
+ function handoffBlock(handoff, now) {
32
+ if (!handoff)
33
+ return [];
34
+ return section(`Last handoff (${formatDay(handoff.at, now)}):`, handoff.lines.map((line) => ` ${line}`));
35
+ }
36
+ export function renderCatchup(data, now = Date.now()) {
37
+ const { status, commits } = gitLines(data);
38
+ const blocks = [
39
+ ...handoffBlock(data.handoff, now),
40
+ ...chatBlock(data.lastChat, now),
41
+ ...section('Still to do (from facts):', bullets(data.todos)),
42
+ ...section('Decisions and dead ends (from facts):', bullets(data.decisions)),
43
+ ...section('Not committed yet (recorded work):', bullets(data.uncommitted)),
44
+ ...branchLine(data.git),
45
+ ...section('Git status:', status),
46
+ ...section('Recent commits:', commits),
47
+ ];
48
+ return blocks.length === 0 ? NOTHING_RECORDED : blocks.join('\n').trimEnd();
49
+ }
@@ -0,0 +1,13 @@
1
+ import type { BackfillResult, BackfillStep } from '../facts/distill.js';
2
+ import type { BudgetUsage } from '../util/daily-budget.js';
3
+ export interface BackfillPrinterOptions {
4
+ write: (text: string) => void;
5
+ tty: boolean;
6
+ every?: (tick: () => void, ms: number) => () => void;
7
+ }
8
+ export interface BackfillPrinter {
9
+ step: (step: BackfillStep) => void;
10
+ finish: (result: BackfillResult, usage: BudgetUsage, dailyLimit: number) => void;
11
+ }
12
+ export declare function stopLine(result: BackfillResult, usage: BudgetUsage, dailyLimit: number): string;
13
+ export declare function createBackfillPrinter(options: BackfillPrinterOptions): BackfillPrinter;
@@ -0,0 +1,78 @@
1
+ import { describePause } from '../util/daily-budget.js';
2
+ const FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
3
+ const FRAME_MS = 120;
4
+ const CLEAR_LINE = '\r\u001b[K';
5
+ function everyInterval(tick, ms) {
6
+ const timer = setInterval(tick, ms);
7
+ timer.unref();
8
+ return () => clearInterval(timer);
9
+ }
10
+ export function stopLine(result, usage, dailyLimit) {
11
+ const left = `${result.remaining} chat(s) still waiting`;
12
+ if (result.stopped === 'failed') {
13
+ const reason = usage.lastFailure?.reason ?? 'the call failed';
14
+ return `stopped : a Haiku call failed (${reason}), ${left}`;
15
+ }
16
+ const pause = describePause(usage);
17
+ const why = pause ? `paused ${pause}` : `the daily limit of ${dailyLimit} calls is used up`;
18
+ return `stopped : ${why}, ${left}`;
19
+ }
20
+ function factsMade(count) {
21
+ return `${count} ${count === 1 ? 'fact' : 'facts'} made`;
22
+ }
23
+ function headerLine(total) {
24
+ if (total === 0)
25
+ return 'nothing waiting: every recent chat is already turned into facts\n';
26
+ return `${total} chat(s) waiting. This can take a few minutes, each chat needs one or more Haiku calls.\n`;
27
+ }
28
+ function progressLine(step) {
29
+ return `${step.index} of ${step.total} chats, ${factsMade(step.facts)}\n`;
30
+ }
31
+ function closingLine(result, usage, dailyLimit) {
32
+ if (result.stopped !== 'done')
33
+ return `${stopLine(result, usage, dailyLimit)}\n`;
34
+ if (result.distilled === 0)
35
+ return '';
36
+ return `done : ${result.distilled} chat(s) turned into ${result.facts} fact(s)\n`;
37
+ }
38
+ export function createBackfillPrinter(options) {
39
+ const { write, tty, every = everyInterval } = options;
40
+ let stopSpinner = null;
41
+ const clearSpinner = () => {
42
+ if (!stopSpinner)
43
+ return;
44
+ stopSpinner();
45
+ stopSpinner = null;
46
+ write(CLEAR_LINE);
47
+ };
48
+ const startSpinner = (label) => {
49
+ let frame = 0;
50
+ const draw = () => {
51
+ write(`${CLEAR_LINE}${FRAMES[frame % FRAMES.length]} ${label}`);
52
+ frame += 1;
53
+ };
54
+ draw();
55
+ stopSpinner = every(draw, FRAME_MS);
56
+ };
57
+ return {
58
+ step(step) {
59
+ switch (step.kind) {
60
+ case 'begin':
61
+ write(headerLine(step.total));
62
+ return;
63
+ case 'start':
64
+ if (tty)
65
+ startSpinner(`chat ${step.index} of ${step.total}`);
66
+ return;
67
+ case 'done':
68
+ clearSpinner();
69
+ write(progressLine(step));
70
+ return;
71
+ }
72
+ },
73
+ finish(result, usage, dailyLimit) {
74
+ clearSpinner();
75
+ write(closingLine(result, usage, dailyLimit));
76
+ },
77
+ };
78
+ }
@@ -0,0 +1 @@
1
+ export declare function cmdCatchup(): Promise<void>;
@@ -0,0 +1,14 @@
1
+ import { gatherCatchup } from '../../catchup/gather.js';
2
+ import { renderCatchup } from '../../catchup/render.js';
3
+ import { createContext } from '../../context.js';
4
+ import { resolveProject } from '../../util/project.js';
5
+ export async function cmdCatchup() {
6
+ const project = resolveProject(undefined);
7
+ const ctx = await createContext();
8
+ try {
9
+ console.log(renderCatchup(await gatherCatchup(ctx, project)));
10
+ }
11
+ finally {
12
+ await ctx.close();
13
+ }
14
+ }
@@ -1,8 +1,10 @@
1
1
  import { setConfigValue } from '../../config/index.js';
2
+ import { createBackfillPrinter } from '../backfill-output.js';
2
3
  import { createContext } from '../../context.js';
3
4
  import { distillUsage } from '../../facts/budget.js';
4
5
  import { importClaudeMemory } from '../../facts/claude-memory.js';
5
6
  import { FACTS_JOB, backfill, distillSession, factCounts, pendingSessions, } from '../../facts/distill.js';
7
+ import { runHeadlessResult } from '../../util/claude-cli.js';
6
8
  import { describePause } from '../../util/daily-budget.js';
7
9
  import { finishJob, releaseJob } from '../../util/job-lock.js';
8
10
  import { resolveProject } from '../../util/project.js';
@@ -39,8 +41,17 @@ async function runBackfill(project) {
39
41
  const ctx = await createContext();
40
42
  try {
41
43
  await importClaudeMemory(ctx, project);
42
- if (ctx.config.distill.enabled)
43
- await backfill(ctx, project);
44
+ if (ctx.config.distill.enabled) {
45
+ const printer = createBackfillPrinter({
46
+ write: (text) => process.stdout.write(text),
47
+ tty: process.stdout.isTTY === true,
48
+ });
49
+ const result = await backfill(ctx, project, runHeadlessResult, printer.step);
50
+ printer.finish(result, distillUsage(), ctx.config.distill.dailyLimit);
51
+ }
52
+ else {
53
+ console.log('distill : off, so no chats were turned into facts (claude-db distill on)');
54
+ }
44
55
  }
45
56
  finally {
46
57
  await ctx.close();
@@ -1 +1,3 @@
1
+ import type { ClaudeLocation } from '../../util/claude-binary.js';
1
2
  export declare function cmdDoctor(argv: (string | undefined)[]): Promise<void>;
3
+ export declare function describeClaude(location: ClaudeLocation | null): string;
@@ -8,6 +8,12 @@ import { ourHookFile } from '../install.js';
8
8
  import { settingsPathFor } from '../paths.js';
9
9
  import { existsSync, readFileSync } from 'node:fs';
10
10
  import { toShortId } from '../../util/shortid.js';
11
+ import { resolveClaude } from '../../util/claude-binary.js';
12
+ import { runHeadlessResult } from '../../util/claude-cli.js';
13
+ import { describeSkills } from '../skills.js';
14
+ const HAIKU_PROBE_PROMPT = 'Reply with the single word: ok';
15
+ const HAIKU_PROBE_TIMEOUT_MS = 60_000;
16
+ const REPLY_PREVIEW_CHARS = 40;
11
17
  export async function cmdDoctor(argv) {
12
18
  const base = loadConfig();
13
19
  const ctx = await createContext({
@@ -28,10 +34,43 @@ export async function cmdDoctor(argv) {
28
34
  console.log('hint : builtin embeddings are keyword-grade. For semantic vectors:');
29
35
  console.log(' npm i -g @xenova/transformers && claude-db reembed');
30
36
  }
31
- checkWiring(resolveProject(undefined));
32
- const healthy = argv.includes('--deep') ? await deepCheck(ctx) : true;
37
+ const project = resolveProject(undefined);
38
+ checkWiring(project);
39
+ console.log(describeSkills(project));
40
+ const claude = resolveClaude();
41
+ console.log(describeClaude(claude));
42
+ const deepOk = argv.includes('--deep') ? await runDeepChecks(ctx, claude) : true;
33
43
  await ctx.close();
34
- process.exit(reachable && healthy ? 0 : 1);
44
+ process.exit(reachable && deepOk ? 0 : 1);
45
+ }
46
+ async function runDeepChecks(ctx, claude) {
47
+ const storeOk = await deepCheck(ctx);
48
+ const haikuOk = await haikuCheck(ctx, claude);
49
+ return storeOk && haikuOk;
50
+ }
51
+ export function describeClaude(location) {
52
+ if (location)
53
+ return `claude : ${location.path} (from ${location.source})`;
54
+ return [
55
+ 'claude : NOT FOUND, so facts and picks cannot run',
56
+ ' fix: put claude on PATH, or set CLAUDE_CODE_EXECPATH to its full path',
57
+ ].join('\n');
58
+ }
59
+ async function haikuCheck(ctx, claude) {
60
+ const model = ctx.config.distill.model;
61
+ console.log(`\nhaiku check (one small ${model} call, not counted against the daily limits)`);
62
+ if (!claude) {
63
+ console.log(' FAIL call — claude was not found');
64
+ return false;
65
+ }
66
+ const result = await runHeadlessResult(HAIKU_PROBE_PROMPT, model, HAIKU_PROBE_TIMEOUT_MS);
67
+ if (!result.ok) {
68
+ console.log(` FAIL call — ${result.reason}`);
69
+ return false;
70
+ }
71
+ const reply = result.stdout.trim().slice(0, REPLY_PREVIEW_CHARS);
72
+ console.log(` ok call — ${reply || 'empty reply'}`);
73
+ return true;
35
74
  }
36
75
  function checkWiring(project) {
37
76
  const problems = [];
@@ -66,8 +66,9 @@ export async function cmdProjects() {
66
66
  return;
67
67
  }
68
68
  console.log(`database: ${redact(ctx.config.database)}\n`);
69
+ const names = await ctx.store.projectScope(here);
69
70
  for (const entry of projects) {
70
- const marker = entry.project === here ? '*' : ' ';
71
+ const marker = names.includes(entry.project) ? '*' : ' ';
71
72
  const date = new Date(entry.lastActive).toISOString().slice(0, 10);
72
73
  console.log(`${marker} ${String(entry.observations).padStart(5)} ${date} ${entry.project}`);
73
74
  }