claude-db 0.4.1 → 0.5.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 (203) hide show
  1. package/CHANGELOG.md +411 -0
  2. package/README.md +62 -94
  3. package/dist/capture/command.d.ts +0 -14
  4. package/dist/capture/command.js +0 -23
  5. package/dist/capture/flush.d.ts +1 -50
  6. package/dist/capture/flush.js +4 -63
  7. package/dist/capture/git.js +0 -20
  8. package/dist/capture/identity.d.ts +0 -17
  9. package/dist/capture/identity.js +1 -21
  10. package/dist/capture/index.d.ts +1 -0
  11. package/dist/capture/index.js +1 -0
  12. package/dist/capture/manual.d.ts +0 -19
  13. package/dist/capture/manual.js +0 -0
  14. package/dist/capture/progress.d.ts +4 -0
  15. package/dist/capture/progress.js +33 -0
  16. package/dist/capture/transcript.d.ts +0 -45
  17. package/dist/capture/transcript.js +4 -70
  18. package/dist/capture/turn-extractor.d.ts +0 -15
  19. package/dist/capture/turn-extractor.js +1 -104
  20. package/dist/cli/args.d.ts +4 -0
  21. package/dist/cli/args.js +16 -0
  22. package/dist/cli/commands/doctor.d.ts +1 -0
  23. package/dist/cli/commands/doctor.js +76 -0
  24. package/dist/cli/commands/graph.d.ts +2 -0
  25. package/dist/cli/commands/graph.js +93 -0
  26. package/dist/cli/commands/insight.d.ts +3 -0
  27. package/dist/cli/commands/insight.js +129 -0
  28. package/dist/cli/commands/maintain.d.ts +3 -0
  29. package/dist/cli/commands/maintain.js +77 -0
  30. package/dist/cli/commands/memory.d.ts +3 -0
  31. package/dist/cli/commands/memory.js +77 -0
  32. package/dist/cli/commands/seed.d.ts +1 -0
  33. package/dist/cli/commands/seed.js +43 -0
  34. package/dist/cli/commands/setup.d.ts +4 -0
  35. package/dist/cli/commands/setup.js +156 -0
  36. package/dist/cli/commands/sync.d.ts +1 -0
  37. package/dist/cli/commands/sync.js +95 -0
  38. package/dist/cli/commands/transfer.d.ts +9 -0
  39. package/dist/cli/commands/transfer.js +129 -0
  40. package/dist/cli/commands/use.d.ts +1 -0
  41. package/dist/cli/commands/use.js +90 -0
  42. package/dist/cli/constants.d.ts +2 -0
  43. package/dist/cli/constants.js +4 -0
  44. package/dist/cli/files.d.ts +4 -0
  45. package/dist/cli/files.js +33 -0
  46. package/dist/cli/index.js +15 -1080
  47. package/dist/cli/install.d.ts +1 -59
  48. package/dist/cli/install.js +5 -194
  49. package/dist/cli/instructions.d.ts +5 -0
  50. package/dist/cli/instructions.js +55 -0
  51. package/dist/cli/paths.d.ts +5 -0
  52. package/dist/cli/paths.js +19 -0
  53. package/dist/cli/refresh.d.ts +1 -0
  54. package/dist/cli/refresh.js +25 -0
  55. package/dist/cli/usage.d.ts +1 -0
  56. package/dist/cli/usage.js +39 -0
  57. package/dist/config/load.d.ts +0 -5
  58. package/dist/config/load.js +1 -8
  59. package/dist/config/schema.js +2 -58
  60. package/dist/context.d.ts +0 -10
  61. package/dist/context.js +0 -16
  62. package/dist/embed/builtin.d.ts +0 -12
  63. package/dist/embed/builtin.js +0 -20
  64. package/dist/embed/embedder.d.ts +0 -14
  65. package/dist/embed/embedder.js +0 -1
  66. package/dist/embed/index.d.ts +0 -9
  67. package/dist/embed/index.js +0 -9
  68. package/dist/embed/local.d.ts +0 -8
  69. package/dist/embed/local.js +0 -12
  70. package/dist/graph/index.d.ts +7 -0
  71. package/dist/graph/index.js +4 -0
  72. package/dist/graph/languages/ecmascript.d.ts +4 -0
  73. package/dist/graph/languages/ecmascript.js +47 -0
  74. package/dist/graph/languages/go.d.ts +2 -0
  75. package/dist/graph/languages/go.js +15 -0
  76. package/dist/graph/languages/index.d.ts +6 -0
  77. package/dist/graph/languages/index.js +20 -0
  78. package/dist/graph/languages/python.d.ts +2 -0
  79. package/dist/graph/languages/python.js +15 -0
  80. package/dist/graph/languages/rules.d.ts +18 -0
  81. package/dist/graph/languages/rules.js +1 -0
  82. package/dist/graph/languages/rust.d.ts +2 -0
  83. package/dist/graph/languages/rust.js +16 -0
  84. package/dist/graph/parser.d.ts +31 -0
  85. package/dist/graph/parser.js +29 -0
  86. package/dist/graph/query/format.d.ts +2 -0
  87. package/dist/graph/query/format.js +41 -0
  88. package/dist/graph/query/index.d.ts +5 -0
  89. package/dist/graph/query/index.js +4 -0
  90. package/dist/graph/query/lookup.d.ts +21 -0
  91. package/dist/graph/query/lookup.js +35 -0
  92. package/dist/graph/query/path.d.ts +2 -0
  93. package/dist/graph/query/path.js +48 -0
  94. package/dist/graph/query/refresh.d.ts +2 -0
  95. package/dist/graph/query/refresh.js +21 -0
  96. package/dist/graph/scan/extract.d.ts +15 -0
  97. package/dist/graph/scan/extract.js +101 -0
  98. package/dist/graph/scan/files.d.ts +12 -0
  99. package/dist/graph/scan/files.js +51 -0
  100. package/dist/graph/scan/index.d.ts +18 -0
  101. package/dist/graph/scan/index.js +44 -0
  102. package/dist/graph/scan/resolve.d.ts +3 -0
  103. package/dist/graph/scan/resolve.js +48 -0
  104. package/dist/hooks/payload.d.ts +0 -8
  105. package/dist/hooks/payload.js +0 -6
  106. package/dist/hooks/relevance.d.ts +0 -17
  107. package/dist/hooks/relevance.js +55 -38
  108. package/dist/hooks/session-end.js +0 -11
  109. package/dist/hooks/session-start.js +33 -14
  110. package/dist/hooks/user-prompt.js +0 -18
  111. package/dist/mcp/render.d.ts +0 -20
  112. package/dist/mcp/render.js +0 -39
  113. package/dist/mcp/server.js +46 -25
  114. package/dist/search/rank.d.ts +0 -14
  115. package/dist/search/rank.js +0 -16
  116. package/dist/search/service.d.ts +1 -32
  117. package/dist/search/service.js +1 -36
  118. package/dist/store/adapter.d.ts +11 -44
  119. package/dist/store/adapter.js +1 -12
  120. package/dist/store/index.d.ts +0 -11
  121. package/dist/store/index.js +0 -11
  122. package/dist/store/mongo/docs.d.ts +61 -0
  123. package/dist/store/mongo/docs.js +106 -0
  124. package/dist/store/mongo/driver.d.ts +1 -15
  125. package/dist/store/mongo/driver.js +0 -15
  126. package/dist/store/mongo/filters.d.ts +6 -0
  127. package/dist/store/mongo/filters.js +18 -0
  128. package/dist/store/mongo/graph.d.ts +12 -0
  129. package/dist/store/mongo/graph.js +61 -0
  130. package/dist/store/mongo/helpers.d.ts +2 -0
  131. package/dist/store/mongo/helpers.js +8 -0
  132. package/dist/store/mongo/index.d.ts +16 -13
  133. package/dist/store/mongo/index.js +52 -295
  134. package/dist/store/mongo/observations.d.ts +10 -0
  135. package/dist/store/mongo/observations.js +97 -0
  136. package/dist/store/mongo/search.d.ts +6 -0
  137. package/dist/store/mongo/search.js +51 -0
  138. package/dist/store/mongo/sessions.d.ts +6 -0
  139. package/dist/store/mongo/sessions.js +24 -0
  140. package/dist/store/mongo/vectorSearch.d.ts +5 -0
  141. package/dist/store/mongo/vectorSearch.js +57 -0
  142. package/dist/store/postgres/driver.d.ts +19 -0
  143. package/dist/store/postgres/driver.js +13 -0
  144. package/dist/store/postgres/filters.d.ts +2 -0
  145. package/dist/store/postgres/filters.js +22 -0
  146. package/dist/store/postgres/graph.d.ts +11 -0
  147. package/dist/store/postgres/graph.js +115 -0
  148. package/dist/store/postgres/index.d.ts +20 -33
  149. package/dist/store/postgres/index.js +43 -428
  150. package/dist/store/postgres/insert.d.ts +3 -0
  151. package/dist/store/postgres/insert.js +59 -0
  152. package/dist/store/postgres/meta.d.ts +10 -0
  153. package/dist/store/postgres/meta.js +54 -0
  154. package/dist/store/postgres/observations.d.ts +10 -0
  155. package/dist/store/postgres/observations.js +139 -0
  156. package/dist/store/postgres/rows.d.ts +6 -0
  157. package/dist/store/postgres/rows.js +74 -0
  158. package/dist/store/postgres/schema.d.ts +3 -0
  159. package/dist/store/postgres/schema.js +84 -0
  160. package/dist/store/postgres/search.d.ts +3 -0
  161. package/dist/store/postgres/search.js +20 -0
  162. package/dist/store/postgres/sessions.d.ts +5 -0
  163. package/dist/store/postgres/sessions.js +26 -0
  164. package/dist/store/postgres/vectorSearch.d.ts +3 -0
  165. package/dist/store/postgres/vectorSearch.js +21 -0
  166. package/dist/store/sqlite/filters.d.ts +9 -0
  167. package/dist/store/sqlite/filters.js +77 -0
  168. package/dist/store/sqlite/graph.d.ts +11 -0
  169. package/dist/store/sqlite/graph.js +100 -0
  170. package/dist/store/sqlite/index.d.ts +12 -10
  171. package/dist/store/sqlite/index.js +41 -379
  172. package/dist/store/sqlite/observations.d.ts +10 -0
  173. package/dist/store/sqlite/observations.js +128 -0
  174. package/dist/store/sqlite/rows.d.ts +8 -0
  175. package/dist/store/sqlite/rows.js +84 -0
  176. package/dist/store/sqlite/schema.sql +42 -2
  177. package/dist/store/sqlite/search.d.ts +5 -0
  178. package/dist/store/sqlite/search.js +86 -0
  179. package/dist/store/sqlite/sessions.d.ts +5 -0
  180. package/dist/store/sqlite/sessions.js +21 -0
  181. package/dist/types.d.ts +47 -40
  182. package/dist/types.js +0 -4
  183. package/dist/update.d.ts +0 -20
  184. package/dist/update.js +4 -29
  185. package/dist/usages/find.d.ts +2 -8
  186. package/dist/usages/find.js +51 -54
  187. package/dist/usages/index.d.ts +1 -1
  188. package/dist/usages/index.js +1 -1
  189. package/dist/util/project.d.ts +0 -12
  190. package/dist/util/project.js +0 -24
  191. package/dist/util/scope.d.ts +0 -9
  192. package/dist/util/scope.js +0 -9
  193. package/dist/util/shortid.d.ts +0 -5
  194. package/dist/util/shortid.js +1 -19
  195. package/dist/util/snippet.d.ts +0 -26
  196. package/dist/util/snippet.js +0 -30
  197. package/dist/util/vector.d.ts +0 -12
  198. package/dist/util/vector.js +0 -12
  199. package/dist/util/warnings.d.ts +0 -11
  200. package/dist/util/warnings.js +0 -11
  201. package/docs/how-it-works.md +183 -0
  202. package/package.json +14 -3
  203. package/skills/cdb-scan/SKILL.md +31 -6
@@ -1,20 +1,4 @@
1
- /**
2
- * Decides whether a shell command is worth remembering.
3
- *
4
- * Agents run far more commands to *look* than to *change*, and the looking is
5
- * worthless later: nobody needs to recall that you grepped for easing curves
6
- * three weeks ago. Capturing it crowds out the handful that genuinely mattered.
7
- *
8
- * So this is an allowlist of consequential operations rather than a blocklist
9
- * of exploration. Exploration is unbounded in variety and impossible to
10
- * enumerate; the operations that change project state are a short, stable list.
11
- *
12
- * Returns null for anything unrecognised, which means "do not store".
13
- */
14
1
  export function classifyCommand(command) {
15
- // Agents chain aggressively: `pnpm lint; echo "==="; git status`. Classifying
16
- // the raw string stores the whole chain as one title, most of which is
17
- // exploration. Split first, then label only the segment that qualified.
18
2
  for (const segment of splitSegments(command)) {
19
3
  for (const rule of RULES) {
20
4
  if (rule.pattern.test(segment)) {
@@ -24,20 +8,13 @@ export function classifyCommand(command) {
24
8
  }
25
9
  return null;
26
10
  }
27
- /** Splits on shell separators, keeping each simple command intact. */
28
11
  function splitSegments(command) {
29
12
  return command
30
13
  .split(/(?:\|\||&&|[;\n|])/)
31
14
  .map((segment) => segment.trim().replace(/\s+/g, ' '))
32
15
  .filter((segment) => segment.length > 0);
33
16
  }
34
- /** Optional leading `cd foo &&`-style noise is already stripped by splitting. */
35
17
  const PM = '(?:npm|pnpm|yarn|bun|npx)';
36
- /**
37
- * Every pattern is anchored to the start of a segment so a bare word inside a
38
- * filename cannot match. `sed -n '1,50p' test.ts` is exploration; `pnpm test`
39
- * is not, and only anchoring tells them apart.
40
- */
41
18
  const RULES = [
42
19
  {
43
20
  pattern: new RegExp(`^${PM} (?:install|add|remove|uninstall|ci)\\b`, 'i'),
@@ -4,58 +4,9 @@ export interface FlushResult {
4
4
  observations: number;
5
5
  summary: string | null;
6
6
  }
7
- /**
8
- * Persists everything new in a session's transcript.
9
- *
10
- * Gating all writes on SessionEnd was the original design and it loses data
11
- * constantly: a session that is force-quit, crashes, or simply stays open for
12
- * days never reaches the hook, so its memory is never written. A session left
13
- * open for two weeks produced hundreds of observations under one id and none
14
- * of them searchable until it finally closed.
15
- *
16
- * Flushing incrementally removes that dependency entirely. It is only safe
17
- * because observation ids are content-derived: re-reading a turn rewrites the
18
- * same row rather than appending a duplicate.
19
- */
20
- export declare function flushSession(ctx: RecallContext, sessionId: string, project: string, transcriptPath?: string,
21
- /**
22
- * Discards the stored recap instead of extending it. A manual flush re-reads
23
- * the whole transcript, so the summary can be rebuilt from scratch — and
24
- * after an upgrade it has to be, or the recap injected at every SessionStart
25
- * keeps quoting titles the new extractor would no longer write.
26
- */
27
- rebuild?: boolean): Promise<FlushResult>;
28
- /**
29
- * Embeddings are an enhancement, never a precondition. A missing model must
30
- * cost semantic recall, not the memory itself.
31
- */
7
+ export declare function flushSession(ctx: RecallContext, sessionId: string, project: string, transcriptPath?: string, rebuild?: boolean): Promise<FlushResult>;
32
8
  export declare function embedObservations(ctx: RecallContext, observations: Observation[]): Promise<void>;
33
- /**
34
- * Recap of the session so far, and the only thing SessionStart injects.
35
- *
36
- * Taking the last three titles of the current flush was close to useless once
37
- * capture became incremental: a flush usually carries a single turn, so the
38
- * recap of an entire day's session was whatever happened to be typed last.
39
- * Carrying the previous summary forward makes it cover the session, and
40
- * ranking by kind keeps a decision over the build command that followed it.
41
- *
42
- * ponytail: first three win, so a decision made late in a long session does
43
- * not displace an earlier one. Rank the session's stored observations instead
44
- * if that turns out to matter.
45
- */
46
9
  export declare function summarize(observations: Observation[], previous?: string): string;
47
10
  export declare function resetCursor(sessionId: string): void;
48
- /** The session is over; its offset is scratch state nothing will read again. */
49
11
  export declare function clearCursor(sessionId: string): void;
50
- /**
51
- * Drops cursors whose transcript no longer exists anywhere.
52
- *
53
- * Clearing on SessionEnd only covers sessions that end after it shipped, so a
54
- * machine that has been running this for a while keeps a file per session it
55
- * ever saw. Harmless, and untidy in a way that makes the rest look unmaintained.
56
- *
57
- * Checked against every transcript on disk rather than this project's, because
58
- * cursors are keyed by session alone: sweeping on a per-project basis would
59
- * delete another project's live cursor and cost it a full re-read.
60
- */
61
12
  export declare function sweepCursors(): number;
@@ -3,30 +3,12 @@ import { dirname, join } from 'node:path';
3
3
  import { CONFIG_DIR } from '../config/index.js';
4
4
  import { readTranscript, sessionIdsOnDisk, transcriptPathFor } from './transcript.js';
5
5
  import { observationsFromTurns } from './turn-extractor.js';
6
- /**
7
- * Persists everything new in a session's transcript.
8
- *
9
- * Gating all writes on SessionEnd was the original design and it loses data
10
- * constantly: a session that is force-quit, crashes, or simply stays open for
11
- * days never reaches the hook, so its memory is never written. A session left
12
- * open for two weeks produced hundreds of observations under one id and none
13
- * of them searchable until it finally closed.
14
- *
15
- * Flushing incrementally removes that dependency entirely. It is only safe
16
- * because observation ids are content-derived: re-reading a turn rewrites the
17
- * same row rather than appending a duplicate.
18
- */
19
- export async function flushSession(ctx, sessionId, project, transcriptPath,
20
- /**
21
- * Discards the stored recap instead of extending it. A manual flush re-reads
22
- * the whole transcript, so the summary can be rebuilt from scratch — and
23
- * after an upgrade it has to be, or the recap injected at every SessionStart
24
- * keeps quoting titles the new extractor would no longer write.
25
- */
26
- rebuild = false) {
6
+ import { closeLandedWork } from './progress.js';
7
+ export async function flushSession(ctx, sessionId, project, transcriptPath, rebuild = false) {
27
8
  const path = transcriptPath ?? transcriptPathFor(project, sessionId);
28
9
  const cursor = readCursor(sessionId);
29
10
  const { turns, nextOffset } = readTranscript(path, cursor);
11
+ await closeLandedWork(ctx.store, project);
30
12
  if (turns.length === 0) {
31
13
  writeCursor(sessionId, nextOffset);
32
14
  return { observations: 0, summary: null };
@@ -49,10 +31,6 @@ rebuild = false) {
49
31
  writeCursor(sessionId, nextOffset);
50
32
  return { observations: observations.length, summary };
51
33
  }
52
- /**
53
- * Embeddings are an enhancement, never a precondition. A missing model must
54
- * cost semantic recall, not the memory itself.
55
- */
56
34
  export async function embedObservations(ctx, observations) {
57
35
  try {
58
36
  const embedder = await ctx.embedder();
@@ -63,8 +41,6 @@ export async function embedObservations(ctx, observations) {
63
41
  const vector = vectors[index];
64
42
  if (vector && vector.length > 0) {
65
43
  obs.embedding = vector;
66
- // Stamped so search can refuse to compare across embedding spaces and
67
- // `reembed` can tell which rows are already current.
68
44
  obs.embedder = embedder.id;
69
45
  }
70
46
  });
@@ -74,7 +50,6 @@ export async function embedObservations(ctx, observations) {
74
50
  `${error instanceof Error ? error.message : String(error)}\n`);
75
51
  }
76
52
  }
77
- /** Least forgettable first. What a session is *for* is usually a decision. */
78
53
  const KIND_RANK = {
79
54
  decision: 0,
80
55
  deadend: 1,
@@ -83,19 +58,6 @@ const KIND_RANK = {
83
58
  pattern: 4,
84
59
  context: 5,
85
60
  };
86
- /**
87
- * Recap of the session so far, and the only thing SessionStart injects.
88
- *
89
- * Taking the last three titles of the current flush was close to useless once
90
- * capture became incremental: a flush usually carries a single turn, so the
91
- * recap of an entire day's session was whatever happened to be typed last.
92
- * Carrying the previous summary forward makes it cover the session, and
93
- * ranking by kind keeps a decision over the build command that followed it.
94
- *
95
- * ponytail: first three win, so a decision made late in a long session does
96
- * not displace an earlier one. Rank the session's stored observations instead
97
- * if that turns out to matter.
98
- */
99
61
  export function summarize(observations, previous) {
100
62
  const kept = previous ? previous.split(' | ').filter(Boolean) : [];
101
63
  for (const obs of [...observations].sort((a, b) => KIND_RANK[a.kind] - KIND_RANK[b.kind])) {
@@ -106,13 +68,6 @@ export function summarize(observations, previous) {
106
68
  }
107
69
  return kept.join(' | ');
108
70
  }
109
- /**
110
- * Per-session byte offset into the transcript.
111
- *
112
- * Stored beside the database rather than in it: this is scratch state about a
113
- * local file, it is worthless on another machine, and it must not sync to a
114
- * shared Postgres or Mongo alongside real memory.
115
- */
116
71
  function cursorName(sessionId) {
117
72
  return `${sessionId.replace(/[^\w-]/g, '_')}.offset`;
118
73
  }
@@ -134,28 +89,14 @@ function writeCursor(sessionId, offset) {
134
89
  mkdirSync(dirname(path), { recursive: true });
135
90
  writeFileSync(path, String(offset), 'utf8');
136
91
  }
137
- catch {
138
- // A lost cursor only costs a redundant re-read, which is idempotent.
139
- }
92
+ catch { }
140
93
  }
141
94
  export function resetCursor(sessionId) {
142
95
  writeCursor(sessionId, 0);
143
96
  }
144
- /** The session is over; its offset is scratch state nothing will read again. */
145
97
  export function clearCursor(sessionId) {
146
98
  rmSync(cursorPath(sessionId), { force: true });
147
99
  }
148
- /**
149
- * Drops cursors whose transcript no longer exists anywhere.
150
- *
151
- * Clearing on SessionEnd only covers sessions that end after it shipped, so a
152
- * machine that has been running this for a while keeps a file per session it
153
- * ever saw. Harmless, and untidy in a way that makes the rest look unmaintained.
154
- *
155
- * Checked against every transcript on disk rather than this project's, because
156
- * cursors are keyed by session alone: sweeping on a per-project basis would
157
- * delete another project's live cursor and cost it a full re-read.
158
- */
159
100
  export function sweepCursors() {
160
101
  const dir = join(CONFIG_DIR, 'cursors');
161
102
  let files;
@@ -2,23 +2,8 @@ import { execFileSync } from 'node:child_process';
2
2
  import { join } from 'node:path';
3
3
  import { observationId } from './identity.js';
4
4
  import { classifyTurn, redact, topLevelDirs } from './turn-extractor.js';
5
- /**
6
- * Builds memory from git history.
7
- *
8
- * A fresh install knows nothing and stays useless for weeks while it fills up,
9
- * which is the worst moment to be asking someone to trust it. Git history is
10
- * already a near-perfect source for exactly the fields an observation wants —
11
- * subject, reasoning, files, author, date — and unlike a profile written by a
12
- * model it is a record of things that actually happened.
13
- *
14
- * Ids derive from the commit sha, so this is safe to re-run: later commits are
15
- * added and earlier ones are rewritten in place rather than duplicated.
16
- */
17
- // Unit and record separators: neither can appear in a commit message, so the
18
- // output parses without any quoting rules.
19
5
  const RECORD = '';
20
6
  const FIELD = '';
21
- /** Releases and formatting sweeps touch many files and explain nothing. */
22
7
  const NOT_WORTH_KEEPING = /^(v?\d+\.\d+\.\d+|merge |revert "|bump |release |chore\(release\)|\d+\.\d+\.\d+$)/i;
23
8
  export function observationsFromGit(project, limit) {
24
9
  const raw = execFileSync('git', [
@@ -41,9 +26,6 @@ export function observationsFromGit(project, limit) {
41
26
  function toObservation(record, project) {
42
27
  if (record.trim().length === 0)
43
28
  return null;
44
- // The format string ends with a separator, so --name-only's paths arrive as
45
- // their own field rather than having to be told apart from the body — which
46
- // cannot be done by looking, since commit bodies contain blank lines too.
47
29
  const [sha, author, date, subject, body = '', paths = ''] = record.split(FIELD);
48
30
  if (!sha || !subject || !date)
49
31
  return null;
@@ -61,8 +43,6 @@ function toObservation(record, project) {
61
43
  return null;
62
44
  const timestamp = createdAt;
63
45
  return {
64
- // The sha alone, so re-seeding rewrites rather than appends and two
65
- // machines seeding the same repository agree on every id.
66
46
  id: observationId('git', 0, sha),
67
47
  sessionId: 'git',
68
48
  project,
@@ -1,19 +1,2 @@
1
- /**
2
- * Who recorded an observation. Meaningless on a personal SQLite file and the
3
- * whole point on a shared Postgres, where "decided X" is far weaker than
4
- * "alex decided X". Captured now because it cannot be backfilled later.
5
- */
6
1
  export declare function currentAuthor(): string | undefined;
7
- /**
8
- * Derives a stable id for an observation from its content.
9
- *
10
- * Random ids make every write path non-idempotent: re-running SessionEnd, or
11
- * flushing a session twice, produces a second copy of the same memory under a
12
- * different primary key, so `INSERT OR REPLACE` cannot collapse them. Search
13
- * then returns near-identical pairs and the reader loses trust in the results.
14
- *
15
- * Hashing the session, the turn's timestamp and its prompt means the same turn
16
- * always lands on the same row. Reprocessing becomes a no-op, which is exactly
17
- * what allows memory to be flushed continuously rather than once at the end.
18
- */
19
2
  export declare function observationId(sessionId: string, timestamp: number, seed: string): string;
@@ -1,10 +1,5 @@
1
1
  import { createHash } from 'node:crypto';
2
2
  import { userInfo } from 'node:os';
3
- /**
4
- * Who recorded an observation. Meaningless on a personal SQLite file and the
5
- * whole point on a shared Postgres, where "decided X" is far weaker than
6
- * "alex decided X". Captured now because it cannot be backfilled later.
7
- */
8
3
  export function currentAuthor() {
9
4
  try {
10
5
  return userInfo().username || undefined;
@@ -13,23 +8,8 @@ export function currentAuthor() {
13
8
  return undefined;
14
9
  }
15
10
  }
16
- /**
17
- * Derives a stable id for an observation from its content.
18
- *
19
- * Random ids make every write path non-idempotent: re-running SessionEnd, or
20
- * flushing a session twice, produces a second copy of the same memory under a
21
- * different primary key, so `INSERT OR REPLACE` cannot collapse them. Search
22
- * then returns near-identical pairs and the reader loses trust in the results.
23
- *
24
- * Hashing the session, the turn's timestamp and its prompt means the same turn
25
- * always lands on the same row. Reprocessing becomes a no-op, which is exactly
26
- * what allows memory to be flushed continuously rather than once at the end.
27
- */
28
11
  export function observationId(sessionId, timestamp, seed) {
29
- const digest = createHash('sha256')
30
- .update(`${sessionId} ${timestamp} ${seed}`)
31
- .digest('hex');
32
- // Shaped like a UUID so the short-id prefix rules keep working unchanged.
12
+ const digest = createHash('sha256').update(`${sessionId} ${timestamp} ${seed}`).digest('hex');
33
13
  return [
34
14
  digest.slice(0, 8),
35
15
  digest.slice(8, 12),
@@ -8,3 +8,4 @@ export { observationsFromGit } from './git.js';
8
8
  export { observationsFromTurns, redact } from './turn-extractor.js';
9
9
  export { flushSession, resetCursor, clearCursor, sweepCursors, summarize, embedObservations, } from './flush.js';
10
10
  export type { FlushResult } from './flush.js';
11
+ export { closeLandedWork, openWork } from './progress.js';
@@ -5,3 +5,4 @@ export { readTranscript, sessionIdsOnDisk, transcriptPathFor, transcriptsFor, }
5
5
  export { observationsFromGit } from './git.js';
6
6
  export { observationsFromTurns, redact } from './turn-extractor.js';
7
7
  export { flushSession, resetCursor, clearCursor, sweepCursors, summarize, embedObservations, } from './flush.js';
8
+ export { closeLandedWork, openWork } from './progress.js';
@@ -5,26 +5,7 @@ export interface RememberInput {
5
5
  text: string;
6
6
  kind?: ObservationKind;
7
7
  files?: string[];
8
- /** Extra tags, alongside `manual`. */
9
8
  tags?: string[];
10
- /**
11
- * Stable identity within the project. Remembering the same key again
12
- * overwrites rather than adding a near-duplicate, which is what lets a
13
- * survey of the codebase be re-run as it changes instead of accumulating
14
- * one stale copy per run.
15
- */
16
9
  key?: string;
17
10
  }
18
- /**
19
- * Records something the user stated outright, rather than something inferred
20
- * from a transcript.
21
- *
22
- * Everything else in this package derives memory from what happened. That
23
- * cannot capture a rule, because a rule is not an event: "we always use pnpm
24
- * here" leaves no edit and no command, so the extractor correctly drops it and
25
- * the one thing worth remembering forever is the one thing never stored.
26
- *
27
- * Written through the same shape as captured observations, so it is searched,
28
- * ranked, injected, exported and pruned identically.
29
- */
30
11
  export declare function remember(ctx: RecallContext, input: RememberInput): Promise<Observation>;
Binary file
@@ -0,0 +1,4 @@
1
+ import type { MemoryStore } from '../store/adapter.js';
2
+ import type { Observation } from '../types.js';
3
+ export declare function closeLandedWork(store: MemoryStore, project: string): Promise<number>;
4
+ export declare function openWork(store: MemoryStore, project: string): Promise<Observation[]>;
@@ -0,0 +1,33 @@
1
+ import { execFileSync } from 'node:child_process';
2
+ import { join } from 'node:path';
3
+ const MAX_BUFFER = 16 * 1024 * 1024;
4
+ const OPEN_LIMIT = 500;
5
+ function uncommittedFiles(project) {
6
+ try {
7
+ const raw = execFileSync('git', ['-C', project, 'status', '--porcelain', '-z'], {
8
+ encoding: 'utf8',
9
+ maxBuffer: MAX_BUFFER,
10
+ });
11
+ return new Set(raw
12
+ .split('\0')
13
+ .filter((entry) => entry.length > 3)
14
+ .map((entry) => join(project, entry.slice(3))));
15
+ }
16
+ catch {
17
+ return null;
18
+ }
19
+ }
20
+ export async function closeLandedWork(store, project) {
21
+ const dirty = uncommittedFiles(project);
22
+ if (!dirty)
23
+ return 0;
24
+ const open = await store.list({ project, status: 'open', limit: OPEN_LIMIT });
25
+ const landed = open
26
+ .filter((obs) => obs.files.every((file) => !dirty.has(file)))
27
+ .map((obs) => obs.id);
28
+ return store.closeObservations(landed);
29
+ }
30
+ export async function openWork(store, project) {
31
+ const open = await store.list({ project, status: 'open', limit: OPEN_LIMIT });
32
+ return open.sort((a, b) => b.createdAt - a.createdAt);
33
+ }
@@ -1,61 +1,16 @@
1
- /** One exchange: what was asked, what was reasoned, what was done. */
2
1
  export interface Turn {
3
2
  prompt: string;
4
- /** The assistant's prose for this turn. This is where the reasoning lives. */
5
3
  reasoning: string;
6
- /** Files created or modified during the turn. */
7
4
  files: string[];
8
- /** Shell commands run during the turn. */
9
5
  commands: string[];
10
6
  timestamp: number;
11
- /** Byte offset in the transcript where this turn began. */
12
7
  offset: number;
13
8
  }
14
9
  export interface TranscriptRead {
15
10
  turns: Turn[];
16
- /**
17
- * Where the next read should resume: the start of the final turn, which may
18
- * still be growing. Reprocessing that turn is harmless because observation
19
- * ids are content-derived.
20
- */
21
11
  nextOffset: number;
22
12
  }
23
- /**
24
- * Claude Code already writes a complete record of every session to disk:
25
- * prompts, replies, and tool calls, appended as JSONL.
26
- *
27
- * Reconstructing that from `PostToolUse` hooks produces a strictly worse copy.
28
- * A hook sees a file path and nothing else; it never sees what the user asked
29
- * for or why the agent did what it did. Intent and reasoning are the entire
30
- * value of a memory, and they exist only here.
31
- */
32
13
  export declare function readTranscript(path: string, fromOffset?: number): TranscriptRead;
33
- /**
34
- * Locates the transcript for a session.
35
- *
36
- * Claude Code passes `transcript_path` in the hook payload, which is
37
- * authoritative. The derived path is a fallback for other agents and for
38
- * backfilling sessions recorded before this existed: the project directory is
39
- * the absolute path with separators and dots replaced by dashes.
40
- */
41
14
  export declare function transcriptPathFor(project: string, sessionId: string): string;
42
- /**
43
- * Every transcript belonging to a project, including sessions started from one
44
- * of its subdirectories.
45
- *
46
- * Claude Code files transcripts under the directory the agent was launched in,
47
- * while memory is keyed on the repository root, and those differ the moment
48
- * anyone runs the agent from `repo/frontend`. Candidate directories are found
49
- * by prefix and then confirmed by the `cwd` each transcript records: the slug
50
- * maps both `/` and `.` to `-`, so it cannot tell `~/app` from `~/app-extra`,
51
- * and without the second step a flush would ingest a neighbour's history.
52
- */
53
15
  export declare function transcriptsFor(project: string): string[];
54
- /**
55
- * Every session id with a transcript still on disk, across all projects.
56
- *
57
- * Deliberately not filtered by project: this answers "does this session still
58
- * exist at all", which is the only safe question to ask before discarding
59
- * local state keyed on a session id alone.
60
- */
61
16
  export declare function sessionIdsOnDisk(): string[];
@@ -2,15 +2,6 @@ import { closeSync, fstatSync, openSync, readdirSync, readSync } from 'node:fs';
2
2
  import { homedir } from 'node:os';
3
3
  import { join } from 'node:path';
4
4
  import { resolveProject } from '../util/project.js';
5
- /**
6
- * Claude Code already writes a complete record of every session to disk:
7
- * prompts, replies, and tool calls, appended as JSONL.
8
- *
9
- * Reconstructing that from `PostToolUse` hooks produces a strictly worse copy.
10
- * A hook sees a file path and nothing else; it never sees what the user asked
11
- * for or why the agent did what it did. Intent and reasoning are the entire
12
- * value of a memory, and they exist only here.
13
- */
14
5
  export function readTranscript(path, fromOffset = 0) {
15
6
  let fd;
16
7
  try {
@@ -21,16 +12,10 @@ export function readTranscript(path, fromOffset = 0) {
21
12
  }
22
13
  try {
23
14
  const size = fstatSync(fd).size;
24
- // A rotated or replaced transcript is shorter than where we left off.
25
- // Restarting from zero is correct and cheap: ids are content-derived, so
26
- // anything already stored is simply rewritten in place.
27
15
  const start = fromOffset > size ? 0 : fromOffset;
28
16
  const length = size - start;
29
17
  if (length <= 0)
30
18
  return { turns: [], nextOffset: size };
31
- // Reading only the unseen tail is what keeps this viable: these files reach
32
- // 90MB+ on long-running sessions, and a full read on every prompt would
33
- // dominate hook latency and memory.
34
19
  const buffer = Buffer.allocUnsafe(length);
35
20
  const bytesRead = readSync(fd, buffer, 0, length, start);
36
21
  const raw = buffer.subarray(0, bytesRead).toString('utf8');
@@ -44,13 +29,9 @@ export function readTranscript(path, fromOffset = 0) {
44
29
  try {
45
30
  entries.push({ entry: JSON.parse(line), offset: lineStart });
46
31
  }
47
- catch {
48
- // A torn final line is normal on a file being appended to right now.
49
- }
32
+ catch { }
50
33
  }
51
34
  const turns = groupIntoTurns(entries);
52
- // Hold the cursor at the last turn's start: it is still open and more
53
- // assistant output may yet be appended to it.
54
35
  const nextOffset = turns.length > 0 ? (turns[turns.length - 1]?.offset ?? size) : size;
55
36
  return { turns, nextOffset };
56
37
  }
@@ -58,14 +39,6 @@ export function readTranscript(path, fromOffset = 0) {
58
39
  closeSync(fd);
59
40
  }
60
41
  }
61
- /**
62
- * A turn opens at a user prompt and absorbs everything until the next one.
63
- *
64
- * This grouping is what lets an observation carry intent: the files written
65
- * after "can you create one icon" belong to that request, and saying so is the
66
- * difference between "wrote mouse-scroll-icon.tsx" and "created the first
67
- * Gestures-batch icon because you asked for one".
68
- */
69
42
  function groupIntoTurns(entries) {
70
43
  const turns = [];
71
44
  let current = null;
@@ -73,7 +46,6 @@ function groupIntoTurns(entries) {
73
46
  const timestamp = Date.parse(entry.timestamp ?? '') || Date.now();
74
47
  if (entry.type === 'user') {
75
48
  const text = extractText(entry.message?.content);
76
- // Tool results arrive as `user` entries too; only real prose is a prompt.
77
49
  if (!text || isSyntheticPrompt(text))
78
50
  continue;
79
51
  if (current)
@@ -97,16 +69,13 @@ function groupIntoTurns(entries) {
97
69
  turns.push(current);
98
70
  return turns;
99
71
  }
100
- /** Content is either a plain string or an array of typed blocks. */
101
72
  function extractText(content) {
102
73
  if (typeof content === 'string')
103
74
  return content.trim();
104
75
  if (!Array.isArray(content))
105
76
  return '';
106
77
  return content
107
- .filter((block) => typeof block === 'object' &&
108
- block !== null &&
109
- block.type === 'text')
78
+ .filter((block) => typeof block === 'object' && block !== null && block.type === 'text')
110
79
  .map((block) => block.text)
111
80
  .join('\n')
112
81
  .trim();
@@ -135,10 +104,6 @@ function extractToolCalls(content) {
135
104
  }
136
105
  return calls;
137
106
  }
138
- /**
139
- * Filters entries that are structurally user messages but not things a person
140
- * typed: injected reminders, hook output, interruption notices.
141
- */
142
107
  function isSyntheticPrompt(text) {
143
108
  return (text.includes('<system-reminder>') ||
144
109
  text.includes('<project-memory>') ||
@@ -147,29 +112,10 @@ function isSyntheticPrompt(text) {
147
112
  text.startsWith('[Request interrupted') ||
148
113
  text.startsWith('<local-command'));
149
114
  }
150
- /**
151
- * Locates the transcript for a session.
152
- *
153
- * Claude Code passes `transcript_path` in the hook payload, which is
154
- * authoritative. The derived path is a fallback for other agents and for
155
- * backfilling sessions recorded before this existed: the project directory is
156
- * the absolute path with separators and dots replaced by dashes.
157
- */
158
115
  export function transcriptPathFor(project, sessionId) {
159
116
  const slug = project.replace(/[/.]/g, '-');
160
117
  return join(homedir(), '.claude', 'projects', slug, `${sessionId}.jsonl`);
161
118
  }
162
- /**
163
- * Every transcript belonging to a project, including sessions started from one
164
- * of its subdirectories.
165
- *
166
- * Claude Code files transcripts under the directory the agent was launched in,
167
- * while memory is keyed on the repository root, and those differ the moment
168
- * anyone runs the agent from `repo/frontend`. Candidate directories are found
169
- * by prefix and then confirmed by the `cwd` each transcript records: the slug
170
- * maps both `/` and `.` to `-`, so it cannot tell `~/app` from `~/app-extra`,
171
- * and without the second step a flush would ingest a neighbour's history.
172
- */
173
119
  export function transcriptsFor(project) {
174
120
  const root = join(homedir(), '.claude', 'projects');
175
121
  const slug = project.replace(/[/.]/g, '-');
@@ -198,13 +144,6 @@ export function transcriptsFor(project) {
198
144
  }
199
145
  return transcripts.sort();
200
146
  }
201
- /**
202
- * Every session id with a transcript still on disk, across all projects.
203
- *
204
- * Deliberately not filtered by project: this answers "does this session still
205
- * exist at all", which is the only safe question to ask before discarding
206
- * local state keyed on a session id alone.
207
- */
208
147
  export function sessionIdsOnDisk() {
209
148
  const root = join(homedir(), '.claude', 'projects');
210
149
  const ids = [];
@@ -222,13 +161,10 @@ export function sessionIdsOnDisk() {
222
161
  ids.push(name.slice(0, -'.jsonl'.length));
223
162
  }
224
163
  }
225
- catch {
226
- // Not a directory, or unreadable: nothing to learn from it.
227
- }
164
+ catch { }
228
165
  }
229
166
  return ids;
230
167
  }
231
- /** First cwd recorded in a transcript, without reading a 90MB file. */
232
168
  function transcriptCwd(path) {
233
169
  let fd;
234
170
  try {
@@ -246,9 +182,7 @@ function transcriptCwd(path) {
246
182
  if (typeof cwd === 'string' && cwd.length > 0)
247
183
  return cwd;
248
184
  }
249
- catch {
250
- // Entry without a cwd, or the torn last line of the window.
251
- }
185
+ catch { }
252
186
  }
253
187
  return null;
254
188
  }
@@ -1,22 +1,7 @@
1
1
  import type { Config } from '../config/index.js';
2
2
  import type { Observation, ObservationKind } from '../types.js';
3
3
  import type { Turn } from './transcript.js';
4
- /**
5
- * Builds observations from transcript turns.
6
- *
7
- * One observation per turn, titled by what was asked and bodied by what the
8
- * agent explained. That ordering matters: the prompt is the only record of
9
- * intent, and the assistant's prose is the only record of reasoning. A
10
- * file-path-based capture has access to neither, which is why it can never
11
- * produce a memory worth recalling.
12
- */
13
4
  export declare function observationsFromTurns(turns: Turn[], sessionId: string, project: string, config: Config): Observation[];
14
- /**
15
- * The first path segment under the project root, which is the repository name
16
- * when the project directory holds several repos, and the top-level source
17
- * folder when it is one repo. Tags carry real weight in every backend's index,
18
- * so this is what makes a pooled memory filterable by where the work happened.
19
- */
20
5
  export declare function topLevelDirs(files: string[], project: string): string[];
21
6
  export declare function classifyTurn(turn: Turn): ObservationKind;
22
7
  export declare function redact(text: string): string;