claude-db 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +201 -0
- package/README.md +306 -0
- package/dist/capture/command.d.ts +20 -0
- package/dist/capture/command.js +81 -0
- package/dist/capture/flush.d.ts +20 -0
- package/dist/capture/flush.js +102 -0
- package/dist/capture/identity.d.ts +13 -0
- package/dist/capture/identity.js +26 -0
- package/dist/capture/index.d.ts +7 -0
- package/dist/capture/index.js +5 -0
- package/dist/capture/transcript.d.ts +41 -0
- package/dist/capture/transcript.js +160 -0
- package/dist/capture/turn-extractor.d.ts +13 -0
- package/dist/capture/turn-extractor.js +135 -0
- package/dist/cli/index.d.ts +2 -0
- package/dist/cli/index.js +349 -0
- package/dist/cli/install.d.ts +40 -0
- package/dist/cli/install.js +156 -0
- package/dist/config/index.d.ts +3 -0
- package/dist/config/index.js +2 -0
- package/dist/config/load.d.ts +11 -0
- package/dist/config/load.js +31 -0
- package/dist/config/schema.d.ts +28 -0
- package/dist/config/schema.js +66 -0
- package/dist/context.d.ts +22 -0
- package/dist/context.js +25 -0
- package/dist/embed/builtin.d.ts +20 -0
- package/dist/embed/builtin.js +66 -0
- package/dist/embed/embedder.d.ts +27 -0
- package/dist/embed/embedder.js +18 -0
- package/dist/embed/index.d.ts +15 -0
- package/dist/embed/index.js +39 -0
- package/dist/embed/local.d.ts +17 -0
- package/dist/embed/local.js +41 -0
- package/dist/hooks/payload.d.ts +21 -0
- package/dist/hooks/payload.js +33 -0
- package/dist/hooks/relevance.d.ts +20 -0
- package/dist/hooks/relevance.js +84 -0
- package/dist/hooks/session-end.d.ts +2 -0
- package/dist/hooks/session-end.js +35 -0
- package/dist/hooks/session-start.d.ts +2 -0
- package/dist/hooks/session-start.js +46 -0
- package/dist/hooks/user-prompt.d.ts +2 -0
- package/dist/hooks/user-prompt.js +56 -0
- package/dist/index.d.ts +10 -0
- package/dist/index.js +5 -0
- package/dist/mcp/server.d.ts +8 -0
- package/dist/mcp/server.js +87 -0
- package/dist/search/index.d.ts +2 -0
- package/dist/search/index.js +2 -0
- package/dist/search/rank.d.ts +17 -0
- package/dist/search/rank.js +43 -0
- package/dist/search/service.d.ts +44 -0
- package/dist/search/service.js +78 -0
- package/dist/store/adapter.d.ts +47 -0
- package/dist/store/adapter.js +1 -0
- package/dist/store/index.d.ts +14 -0
- package/dist/store/index.js +39 -0
- package/dist/store/mongo/driver.d.ts +44 -0
- package/dist/store/mongo/driver.js +28 -0
- package/dist/store/mongo/index.d.ts +36 -0
- package/dist/store/mongo/index.js +275 -0
- package/dist/store/postgres/index.d.ts +30 -0
- package/dist/store/postgres/index.js +289 -0
- package/dist/store/sqlite/index.d.ts +30 -0
- package/dist/store/sqlite/index.js +309 -0
- package/dist/store/sqlite/schema.sql +61 -0
- package/dist/types.d.ts +55 -0
- package/dist/types.js +5 -0
- package/dist/util/project.d.ts +14 -0
- package/dist/util/project.js +24 -0
- package/dist/util/scope.d.ts +10 -0
- package/dist/util/scope.js +17 -0
- package/dist/util/shortid.d.ts +11 -0
- package/dist/util/shortid.js +36 -0
- package/dist/util/vector.d.ts +5 -0
- package/dist/util/vector.js +17 -0
- package/dist/util/warnings.d.ts +12 -0
- package/dist/util/warnings.js +27 -0
- package/package.json +96 -0
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
|
|
2
|
+
import { dirname, join } from 'node:path';
|
|
3
|
+
import { CONFIG_DIR } from '../config/index.js';
|
|
4
|
+
import { readTranscript, transcriptPathFor } from './transcript.js';
|
|
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
|
+
const path = transcriptPath ?? transcriptPathFor(project, sessionId);
|
|
21
|
+
const cursor = readCursor(sessionId);
|
|
22
|
+
const { turns, nextOffset } = readTranscript(path, cursor);
|
|
23
|
+
if (turns.length === 0) {
|
|
24
|
+
writeCursor(sessionId, nextOffset);
|
|
25
|
+
return { observations: 0, summary: null };
|
|
26
|
+
}
|
|
27
|
+
const observations = observationsFromTurns(turns, sessionId, project, ctx.config);
|
|
28
|
+
if (observations.length === 0) {
|
|
29
|
+
writeCursor(sessionId, nextOffset);
|
|
30
|
+
return { observations: 0, summary: null };
|
|
31
|
+
}
|
|
32
|
+
await embedAll(ctx, observations);
|
|
33
|
+
await ctx.store.insertObservations(observations);
|
|
34
|
+
const summary = summarize(observations);
|
|
35
|
+
await ctx.store.upsertSession({
|
|
36
|
+
id: sessionId,
|
|
37
|
+
project,
|
|
38
|
+
startedAt: observations[0]?.createdAt ?? Date.now(),
|
|
39
|
+
summary,
|
|
40
|
+
});
|
|
41
|
+
writeCursor(sessionId, nextOffset);
|
|
42
|
+
return { observations: observations.length, summary };
|
|
43
|
+
}
|
|
44
|
+
/**
|
|
45
|
+
* Embeddings are an enhancement, never a precondition. A missing model must
|
|
46
|
+
* cost semantic recall, not the memory itself.
|
|
47
|
+
*/
|
|
48
|
+
async function embedAll(ctx, observations) {
|
|
49
|
+
try {
|
|
50
|
+
const embedder = await ctx.embedder();
|
|
51
|
+
if (embedder.dimensions === 0)
|
|
52
|
+
return;
|
|
53
|
+
const vectors = await embedder.embed(observations.map((obs) => `${obs.title}\n${obs.body}`));
|
|
54
|
+
observations.forEach((obs, index) => {
|
|
55
|
+
const vector = vectors[index];
|
|
56
|
+
if (vector && vector.length > 0)
|
|
57
|
+
obs.embedding = vector;
|
|
58
|
+
});
|
|
59
|
+
}
|
|
60
|
+
catch (error) {
|
|
61
|
+
process.stderr.write(`[claude-db] embedding skipped: ` +
|
|
62
|
+
`${error instanceof Error ? error.message : String(error)}\n`);
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
/** Recap built from what was accomplished, not from file counts. */
|
|
66
|
+
function summarize(observations) {
|
|
67
|
+
const titles = observations.slice(-3).map((obs) => obs.title);
|
|
68
|
+
const extra = observations.length - titles.length;
|
|
69
|
+
return `${titles.join(' | ')}${extra > 0 ? ` (+${extra} earlier)` : ''}`;
|
|
70
|
+
}
|
|
71
|
+
/**
|
|
72
|
+
* Per-session byte offset into the transcript.
|
|
73
|
+
*
|
|
74
|
+
* Stored beside the database rather than in it: this is scratch state about a
|
|
75
|
+
* local file, it is worthless on another machine, and it must not sync to a
|
|
76
|
+
* shared Postgres or Mongo alongside real memory.
|
|
77
|
+
*/
|
|
78
|
+
function cursorPath(sessionId) {
|
|
79
|
+
return join(CONFIG_DIR, 'cursors', `${sessionId.replace(/[^\w-]/g, '_')}.offset`);
|
|
80
|
+
}
|
|
81
|
+
function readCursor(sessionId) {
|
|
82
|
+
try {
|
|
83
|
+
const value = Number.parseInt(readFileSync(cursorPath(sessionId), 'utf8'), 10);
|
|
84
|
+
return Number.isFinite(value) && value >= 0 ? value : 0;
|
|
85
|
+
}
|
|
86
|
+
catch {
|
|
87
|
+
return 0;
|
|
88
|
+
}
|
|
89
|
+
}
|
|
90
|
+
function writeCursor(sessionId, offset) {
|
|
91
|
+
const path = cursorPath(sessionId);
|
|
92
|
+
try {
|
|
93
|
+
mkdirSync(dirname(path), { recursive: true });
|
|
94
|
+
writeFileSync(path, String(offset), 'utf8');
|
|
95
|
+
}
|
|
96
|
+
catch {
|
|
97
|
+
// A lost cursor only costs a redundant re-read, which is idempotent.
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
export function resetCursor(sessionId) {
|
|
101
|
+
writeCursor(sessionId, 0);
|
|
102
|
+
}
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Derives a stable id for an observation from its content.
|
|
3
|
+
*
|
|
4
|
+
* Random ids make every write path non-idempotent: re-running SessionEnd, or
|
|
5
|
+
* flushing a session twice, produces a second copy of the same memory under a
|
|
6
|
+
* different primary key, so `INSERT OR REPLACE` cannot collapse them. Search
|
|
7
|
+
* then returns near-identical pairs and the reader loses trust in the results.
|
|
8
|
+
*
|
|
9
|
+
* Hashing the session, the turn's timestamp and its prompt means the same turn
|
|
10
|
+
* always lands on the same row. Reprocessing becomes a no-op, which is exactly
|
|
11
|
+
* what allows memory to be flushed continuously rather than once at the end.
|
|
12
|
+
*/
|
|
13
|
+
export declare function observationId(sessionId: string, timestamp: number, seed: string): string;
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
import { createHash } from 'node:crypto';
|
|
2
|
+
/**
|
|
3
|
+
* Derives a stable id for an observation from its content.
|
|
4
|
+
*
|
|
5
|
+
* Random ids make every write path non-idempotent: re-running SessionEnd, or
|
|
6
|
+
* flushing a session twice, produces a second copy of the same memory under a
|
|
7
|
+
* different primary key, so `INSERT OR REPLACE` cannot collapse them. Search
|
|
8
|
+
* then returns near-identical pairs and the reader loses trust in the results.
|
|
9
|
+
*
|
|
10
|
+
* Hashing the session, the turn's timestamp and its prompt means the same turn
|
|
11
|
+
* always lands on the same row. Reprocessing becomes a no-op, which is exactly
|
|
12
|
+
* what allows memory to be flushed continuously rather than once at the end.
|
|
13
|
+
*/
|
|
14
|
+
export function observationId(sessionId, timestamp, seed) {
|
|
15
|
+
const digest = createHash('sha256')
|
|
16
|
+
.update(`${sessionId} ${timestamp} ${seed}`)
|
|
17
|
+
.digest('hex');
|
|
18
|
+
// Shaped like a UUID so the short-id prefix rules keep working unchanged.
|
|
19
|
+
return [
|
|
20
|
+
digest.slice(0, 8),
|
|
21
|
+
digest.slice(8, 12),
|
|
22
|
+
digest.slice(12, 16),
|
|
23
|
+
digest.slice(16, 20),
|
|
24
|
+
digest.slice(20, 32),
|
|
25
|
+
].join('-');
|
|
26
|
+
}
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
export { classifyCommand } from './command.js';
|
|
2
|
+
export { observationId } from './identity.js';
|
|
3
|
+
export { readTranscript, transcriptPathFor } from './transcript.js';
|
|
4
|
+
export type { Turn, TranscriptRead } from './transcript.js';
|
|
5
|
+
export { observationsFromTurns } from './turn-extractor.js';
|
|
6
|
+
export { flushSession, resetCursor } from './flush.js';
|
|
7
|
+
export type { FlushResult } from './flush.js';
|
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
export { classifyCommand } from './command.js';
|
|
2
|
+
export { observationId } from './identity.js';
|
|
3
|
+
export { readTranscript, transcriptPathFor } from './transcript.js';
|
|
4
|
+
export { observationsFromTurns } from './turn-extractor.js';
|
|
5
|
+
export { flushSession, resetCursor } from './flush.js';
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
/** One exchange: what was asked, what was reasoned, what was done. */
|
|
2
|
+
export interface Turn {
|
|
3
|
+
prompt: string;
|
|
4
|
+
/** The assistant's prose for this turn. This is where the reasoning lives. */
|
|
5
|
+
reasoning: string;
|
|
6
|
+
/** Files created or modified during the turn. */
|
|
7
|
+
files: string[];
|
|
8
|
+
/** Shell commands run during the turn. */
|
|
9
|
+
commands: string[];
|
|
10
|
+
timestamp: number;
|
|
11
|
+
/** Byte offset in the transcript where this turn began. */
|
|
12
|
+
offset: number;
|
|
13
|
+
}
|
|
14
|
+
export interface TranscriptRead {
|
|
15
|
+
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
|
+
nextOffset: number;
|
|
22
|
+
}
|
|
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
|
+
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
|
+
export declare function transcriptPathFor(project: string, sessionId: string): string;
|
|
@@ -0,0 +1,160 @@
|
|
|
1
|
+
import { closeSync, fstatSync, openSync, readSync } from 'node:fs';
|
|
2
|
+
import { homedir } from 'node:os';
|
|
3
|
+
import { join } from 'node:path';
|
|
4
|
+
/**
|
|
5
|
+
* Claude Code already writes a complete record of every session to disk:
|
|
6
|
+
* prompts, replies, and tool calls, appended as JSONL.
|
|
7
|
+
*
|
|
8
|
+
* Reconstructing that from `PostToolUse` hooks produces a strictly worse copy.
|
|
9
|
+
* A hook sees a file path and nothing else; it never sees what the user asked
|
|
10
|
+
* for or why the agent did what it did. Intent and reasoning are the entire
|
|
11
|
+
* value of a memory, and they exist only here.
|
|
12
|
+
*/
|
|
13
|
+
export function readTranscript(path, fromOffset = 0) {
|
|
14
|
+
let fd;
|
|
15
|
+
try {
|
|
16
|
+
fd = openSync(path, 'r');
|
|
17
|
+
}
|
|
18
|
+
catch {
|
|
19
|
+
return { turns: [], nextOffset: fromOffset };
|
|
20
|
+
}
|
|
21
|
+
try {
|
|
22
|
+
const size = fstatSync(fd).size;
|
|
23
|
+
// A rotated or replaced transcript is shorter than where we left off.
|
|
24
|
+
// Restarting from zero is correct and cheap: ids are content-derived, so
|
|
25
|
+
// anything already stored is simply rewritten in place.
|
|
26
|
+
const start = fromOffset > size ? 0 : fromOffset;
|
|
27
|
+
const length = size - start;
|
|
28
|
+
if (length <= 0)
|
|
29
|
+
return { turns: [], nextOffset: size };
|
|
30
|
+
// Reading only the unseen tail is what keeps this viable: these files reach
|
|
31
|
+
// 90MB+ on long-running sessions, and a full read on every prompt would
|
|
32
|
+
// dominate hook latency and memory.
|
|
33
|
+
const buffer = Buffer.allocUnsafe(length);
|
|
34
|
+
const bytesRead = readSync(fd, buffer, 0, length, start);
|
|
35
|
+
const raw = buffer.subarray(0, bytesRead).toString('utf8');
|
|
36
|
+
const entries = [];
|
|
37
|
+
let cursor = start;
|
|
38
|
+
for (const line of raw.split('\n')) {
|
|
39
|
+
const lineStart = cursor;
|
|
40
|
+
cursor += Buffer.byteLength(line, 'utf8') + 1;
|
|
41
|
+
if (line.trim().length === 0)
|
|
42
|
+
continue;
|
|
43
|
+
try {
|
|
44
|
+
entries.push({ entry: JSON.parse(line), offset: lineStart });
|
|
45
|
+
}
|
|
46
|
+
catch {
|
|
47
|
+
// A torn final line is normal on a file being appended to right now.
|
|
48
|
+
}
|
|
49
|
+
}
|
|
50
|
+
const turns = groupIntoTurns(entries);
|
|
51
|
+
// Hold the cursor at the last turn's start: it is still open and more
|
|
52
|
+
// assistant output may yet be appended to it.
|
|
53
|
+
const nextOffset = turns.length > 0 ? (turns[turns.length - 1]?.offset ?? size) : size;
|
|
54
|
+
return { turns, nextOffset };
|
|
55
|
+
}
|
|
56
|
+
finally {
|
|
57
|
+
closeSync(fd);
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
/**
|
|
61
|
+
* A turn opens at a user prompt and absorbs everything until the next one.
|
|
62
|
+
*
|
|
63
|
+
* This grouping is what lets an observation carry intent: the files written
|
|
64
|
+
* after "can you create one icon" belong to that request, and saying so is the
|
|
65
|
+
* difference between "wrote mouse-scroll-icon.tsx" and "created the first
|
|
66
|
+
* Gestures-batch icon because you asked for one".
|
|
67
|
+
*/
|
|
68
|
+
function groupIntoTurns(entries) {
|
|
69
|
+
const turns = [];
|
|
70
|
+
let current = null;
|
|
71
|
+
for (const { entry, offset } of entries) {
|
|
72
|
+
const timestamp = Date.parse(entry.timestamp ?? '') || Date.now();
|
|
73
|
+
if (entry.type === 'user') {
|
|
74
|
+
const text = extractText(entry.message?.content);
|
|
75
|
+
// Tool results arrive as `user` entries too; only real prose is a prompt.
|
|
76
|
+
if (!text || isSyntheticPrompt(text))
|
|
77
|
+
continue;
|
|
78
|
+
if (current)
|
|
79
|
+
turns.push(current);
|
|
80
|
+
current = { prompt: text, reasoning: '', files: [], commands: [], timestamp, offset };
|
|
81
|
+
continue;
|
|
82
|
+
}
|
|
83
|
+
if (entry.type === 'assistant' && current) {
|
|
84
|
+
const text = extractText(entry.message?.content);
|
|
85
|
+
if (text)
|
|
86
|
+
current.reasoning = current.reasoning ? `${current.reasoning}\n${text}` : text;
|
|
87
|
+
for (const call of extractToolCalls(entry.message?.content)) {
|
|
88
|
+
if (call.file)
|
|
89
|
+
current.files.push(call.file);
|
|
90
|
+
if (call.command)
|
|
91
|
+
current.commands.push(call.command);
|
|
92
|
+
}
|
|
93
|
+
}
|
|
94
|
+
}
|
|
95
|
+
if (current)
|
|
96
|
+
turns.push(current);
|
|
97
|
+
return turns;
|
|
98
|
+
}
|
|
99
|
+
/** Content is either a plain string or an array of typed blocks. */
|
|
100
|
+
function extractText(content) {
|
|
101
|
+
if (typeof content === 'string')
|
|
102
|
+
return content.trim();
|
|
103
|
+
if (!Array.isArray(content))
|
|
104
|
+
return '';
|
|
105
|
+
return content
|
|
106
|
+
.filter((block) => typeof block === 'object' &&
|
|
107
|
+
block !== null &&
|
|
108
|
+
block.type === 'text')
|
|
109
|
+
.map((block) => block.text)
|
|
110
|
+
.join('\n')
|
|
111
|
+
.trim();
|
|
112
|
+
}
|
|
113
|
+
function extractToolCalls(content) {
|
|
114
|
+
if (!Array.isArray(content))
|
|
115
|
+
return [];
|
|
116
|
+
const calls = [];
|
|
117
|
+
for (const block of content) {
|
|
118
|
+
if (typeof block !== 'object' || block === null)
|
|
119
|
+
continue;
|
|
120
|
+
const typed = block;
|
|
121
|
+
if (typed.type !== 'tool_use')
|
|
122
|
+
continue;
|
|
123
|
+
const input = typed.input ?? {};
|
|
124
|
+
if (typed.name === 'Write' || typed.name === 'Edit' || typed.name === 'MultiEdit') {
|
|
125
|
+
const file = input['file_path'];
|
|
126
|
+
if (typeof file === 'string')
|
|
127
|
+
calls.push({ file });
|
|
128
|
+
}
|
|
129
|
+
else if (typed.name === 'Bash') {
|
|
130
|
+
const command = input['command'];
|
|
131
|
+
if (typeof command === 'string')
|
|
132
|
+
calls.push({ command });
|
|
133
|
+
}
|
|
134
|
+
}
|
|
135
|
+
return calls;
|
|
136
|
+
}
|
|
137
|
+
/**
|
|
138
|
+
* Filters entries that are structurally user messages but not things a person
|
|
139
|
+
* typed: injected reminders, hook output, interruption notices.
|
|
140
|
+
*/
|
|
141
|
+
function isSyntheticPrompt(text) {
|
|
142
|
+
return (text.includes('<system-reminder>') ||
|
|
143
|
+
text.includes('<project-memory>') ||
|
|
144
|
+
text.includes('<recalled-memory>') ||
|
|
145
|
+
text.startsWith('Caveat:') ||
|
|
146
|
+
text.startsWith('[Request interrupted') ||
|
|
147
|
+
text.startsWith('<local-command'));
|
|
148
|
+
}
|
|
149
|
+
/**
|
|
150
|
+
* Locates the transcript for a session.
|
|
151
|
+
*
|
|
152
|
+
* Claude Code passes `transcript_path` in the hook payload, which is
|
|
153
|
+
* authoritative. The derived path is a fallback for other agents and for
|
|
154
|
+
* backfilling sessions recorded before this existed: the project directory is
|
|
155
|
+
* the absolute path with separators and dots replaced by dashes.
|
|
156
|
+
*/
|
|
157
|
+
export function transcriptPathFor(project, sessionId) {
|
|
158
|
+
const slug = project.replace(/[/.]/g, '-');
|
|
159
|
+
return join(homedir(), '.claude', 'projects', slug, `${sessionId}.jsonl`);
|
|
160
|
+
}
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
import type { Config } from '../config/index.js';
|
|
2
|
+
import type { Observation } from '../types.js';
|
|
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
|
+
export declare function observationsFromTurns(turns: Turn[], sessionId: string, project: string, config: Config): Observation[];
|
|
@@ -0,0 +1,135 @@
|
|
|
1
|
+
import { classifyCommand } from './command.js';
|
|
2
|
+
import { observationId } from './identity.js';
|
|
3
|
+
/**
|
|
4
|
+
* Builds observations from transcript turns.
|
|
5
|
+
*
|
|
6
|
+
* One observation per turn, titled by what was asked and bodied by what the
|
|
7
|
+
* agent explained. That ordering matters: the prompt is the only record of
|
|
8
|
+
* intent, and the assistant's prose is the only record of reasoning. A
|
|
9
|
+
* file-path-based capture has access to neither, which is why it can never
|
|
10
|
+
* produce a memory worth recalling.
|
|
11
|
+
*/
|
|
12
|
+
export function observationsFromTurns(turns, sessionId, project, config) {
|
|
13
|
+
return turns
|
|
14
|
+
.filter((turn) => isSubstantive(turn, config))
|
|
15
|
+
.map((turn) => buildObservation(turn, sessionId, project, config));
|
|
16
|
+
}
|
|
17
|
+
/**
|
|
18
|
+
* A turn earns a slot only if it changed something.
|
|
19
|
+
*
|
|
20
|
+
* Conversation that produced no edit and no consequential command is chatter:
|
|
21
|
+
* questions about state, requests to explain, "what's in your context". Those
|
|
22
|
+
* are answered from the repo, not from memory.
|
|
23
|
+
*/
|
|
24
|
+
function isSubstantive(turn, config) {
|
|
25
|
+
const files = turn.files.filter((file) => !isExcluded(file, config.capture.exclude));
|
|
26
|
+
const commands = turn.commands.filter((command) => classifyCommand(command) !== null);
|
|
27
|
+
return files.length > 0 || commands.length > 0;
|
|
28
|
+
}
|
|
29
|
+
function buildObservation(turn, sessionId, project, config) {
|
|
30
|
+
const files = [...new Set(turn.files.filter((f) => !isExcluded(f, config.capture.exclude)))];
|
|
31
|
+
const commands = turn.commands
|
|
32
|
+
.map(classifyCommand)
|
|
33
|
+
.filter((c) => c !== null);
|
|
34
|
+
const body = redact(truncate([
|
|
35
|
+
`Asked: ${turn.prompt}`,
|
|
36
|
+
'',
|
|
37
|
+
turn.reasoning,
|
|
38
|
+
files.length > 0 ? `\nFiles: ${files.map(shortPath).join(', ')}` : '',
|
|
39
|
+
commands.length > 0 ? `Ran: ${commands.map((c) => c.label).join('; ')}` : '',
|
|
40
|
+
]
|
|
41
|
+
.filter((line) => line !== '')
|
|
42
|
+
.join('\n'), config.capture.maxBodyChars));
|
|
43
|
+
return {
|
|
44
|
+
id: observationId(sessionId, turn.timestamp, turn.prompt),
|
|
45
|
+
sessionId,
|
|
46
|
+
project,
|
|
47
|
+
kind: classifyTurn(turn, commands.length > 0),
|
|
48
|
+
title: buildTitle(turn, files),
|
|
49
|
+
body,
|
|
50
|
+
files,
|
|
51
|
+
tags: [],
|
|
52
|
+
createdAt: turn.timestamp,
|
|
53
|
+
};
|
|
54
|
+
}
|
|
55
|
+
/**
|
|
56
|
+
* Prefers the agent's own opening sentence over the raw prompt.
|
|
57
|
+
*
|
|
58
|
+
* The prompt states a request ("can you create one icon"); the reply states
|
|
59
|
+
* what actually happened ("Built mouse-scroll-icon.tsx, first of the Huge
|
|
60
|
+
* Tier 1 Gestures batch"). The second is what someone searching their history
|
|
61
|
+
* is looking for, and it is written in the vocabulary of the codebase.
|
|
62
|
+
*/
|
|
63
|
+
function buildTitle(turn, files) {
|
|
64
|
+
const sentence = firstSentence(stripMarkdown(turn.reasoning));
|
|
65
|
+
if (sentence && sentence.length >= 15)
|
|
66
|
+
return headline(sentence);
|
|
67
|
+
const prompt = firstSentence(turn.prompt);
|
|
68
|
+
if (prompt)
|
|
69
|
+
return headline(prompt);
|
|
70
|
+
return files.length > 0 ? `Changed ${shortPath(files[0] ?? '')}` : 'Session work';
|
|
71
|
+
}
|
|
72
|
+
const TITLE_MAX = 80;
|
|
73
|
+
/**
|
|
74
|
+
* Trims a sentence to a scannable headline.
|
|
75
|
+
*
|
|
76
|
+
* Titles are the entire payload of a layer-1 search result and of the injected
|
|
77
|
+
* memory block, so every character is paid on every query. Cutting at a clause
|
|
78
|
+
* boundary keeps the claim intact where a hard character truncation would sever
|
|
79
|
+
* it mid-phrase.
|
|
80
|
+
*/
|
|
81
|
+
function headline(sentence) {
|
|
82
|
+
if (sentence.length <= TITLE_MAX)
|
|
83
|
+
return sentence;
|
|
84
|
+
const clause = sentence.slice(0, TITLE_MAX);
|
|
85
|
+
const cut = Math.max(clause.lastIndexOf(', '), clause.lastIndexOf(' - '));
|
|
86
|
+
if (cut >= 30)
|
|
87
|
+
return clause.slice(0, cut);
|
|
88
|
+
const word = clause.lastIndexOf(' ');
|
|
89
|
+
return `${clause.slice(0, word > 30 ? word : TITLE_MAX)}...`;
|
|
90
|
+
}
|
|
91
|
+
function classifyTurn(turn, hasCommands) {
|
|
92
|
+
const text = `${turn.prompt} ${turn.reasoning}`.toLowerCase();
|
|
93
|
+
if (/\b(instead of|rather than|chose|decided|because|why we|trade-?off)\b/.test(text)) {
|
|
94
|
+
return 'decision';
|
|
95
|
+
}
|
|
96
|
+
if (/\b(didn'?t work|failed|reverted|abandoned|dead ?end|gave up|doesn'?t scale)\b/.test(text)) {
|
|
97
|
+
return 'deadend';
|
|
98
|
+
}
|
|
99
|
+
if (/\b(fix(ed)?|bug|broken|regression|error|crash)\b/.test(text))
|
|
100
|
+
return 'bugfix';
|
|
101
|
+
if (turn.files.length > 0)
|
|
102
|
+
return 'pattern';
|
|
103
|
+
return hasCommands ? 'context' : 'context';
|
|
104
|
+
}
|
|
105
|
+
function firstSentence(text) {
|
|
106
|
+
const trimmed = text.trim();
|
|
107
|
+
if (trimmed.length === 0)
|
|
108
|
+
return '';
|
|
109
|
+
const match = /^(.+?)(?:[.!?](?:\s|$)|\n)/s.exec(trimmed);
|
|
110
|
+
return (match?.[1] ?? trimmed.split('\n')[0] ?? '').trim();
|
|
111
|
+
}
|
|
112
|
+
/** Markdown links and emphasis read badly in a one-line title. */
|
|
113
|
+
function stripMarkdown(text) {
|
|
114
|
+
return text
|
|
115
|
+
.replace(/\[([^\]]+)\]\([^)]*\)/g, '$1')
|
|
116
|
+
.replace(/[*_`#]/g, '')
|
|
117
|
+
.trim();
|
|
118
|
+
}
|
|
119
|
+
function shortPath(path) {
|
|
120
|
+
return path.split('/').filter(Boolean).slice(-2).join('/');
|
|
121
|
+
}
|
|
122
|
+
function isExcluded(file, patterns) {
|
|
123
|
+
return patterns.some((pattern) => file.includes(pattern));
|
|
124
|
+
}
|
|
125
|
+
const PRIVATE_BLOCK = /<private>[\s\S]*?<\/private>/gi;
|
|
126
|
+
function redact(text) {
|
|
127
|
+
return text
|
|
128
|
+
.replace(PRIVATE_BLOCK, '[redacted]')
|
|
129
|
+
.replace(/\b(sk-[A-Za-z0-9_-]{16,})\b/g, '[redacted-key]')
|
|
130
|
+
.replace(/\b(gh[pousr]_[A-Za-z0-9]{16,})\b/g, '[redacted-token]')
|
|
131
|
+
.replace(/(?<=(password|secret|token|api[_-]?key)"?\s*[:=]\s*)"[^"]+"/gi, '"[redacted]"');
|
|
132
|
+
}
|
|
133
|
+
function truncate(text, max) {
|
|
134
|
+
return text.length <= max ? text : `${text.slice(0, max)}\n... [truncated]`;
|
|
135
|
+
}
|