@tinchu0/knitt 0.1.0-beta.1 → 0.1.0-beta.2

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.
@@ -0,0 +1,91 @@
1
+ import { z } from "zod";
2
+ export function getConversationContext(store, key, options) {
3
+ const maxChars = z
4
+ .number()
5
+ .int()
6
+ .min(256)
7
+ .max(24000)
8
+ .default(12000)
9
+ .parse(options.maxChars);
10
+ const own = store.sessionConversation(key), source = store.selectedSource(key), rows = store.conversationRows(key), events = rows.map((row) => ({
11
+ ...JSON.parse(String(row.payload)),
12
+ receivedAt: String(row.received),
13
+ }));
14
+ const allowed = new Set(events.map((e) => e.eventId));
15
+ const ownCheckpoint = store.latestCheckpoint(key.repoId, own.conversationId), sourceCheckpoint = source
16
+ ? store.latestCheckpoint(key.repoId, source.sourceConversationId, source.throughSeq, source.checkpointSeq)
17
+ : null;
18
+ const revisions = [ownCheckpoint, sourceCheckpoint].filter((cp) => cp !== null);
19
+ const entries = revisions.flatMap((cp) => cp.entries
20
+ .filter((e) => e.evidenceIds.every((id) => allowed.has(id)))
21
+ .map((e) => ({ ...e, conversationId: cp.conversationId })));
22
+ const stale = revisions.some((cp) => rows.some((row) => row.conversation === cp.conversationId &&
23
+ Number(row.seq) > cp.throughSeq));
24
+ const provenance = {
25
+ destination: { ...own, ...store.sessionLocation(key) },
26
+ source: source
27
+ ? {
28
+ ...source,
29
+ ...source.location,
30
+ }
31
+ : null,
32
+ scope: "destination_and_direct_source_only",
33
+ };
34
+ let result = {
35
+ checkpoint: null,
36
+ events: [],
37
+ provenance,
38
+ stale,
39
+ truncated: events.length > 0 || entries.length > 0,
40
+ omitted: { entries: entries.length, events: events.length },
41
+ contentTrust: "untrusted_reference",
42
+ checkpointStatus: revisions.length ? "available" : "missing",
43
+ };
44
+ if (JSON.stringify(result).length > maxChars) {
45
+ result = { ...result, provenance: { omitted: true }, truncated: true };
46
+ // The minimum budget can carry a compact, truthful envelope, not identifiers.
47
+ if (JSON.stringify(result).length > maxChars) {
48
+ delete result.provenance.omitted;
49
+ }
50
+ }
51
+ const checkpoint = {
52
+ entries: [],
53
+ revisions: revisions.map(({ checkpointId, conversationId, throughSeq }) => ({
54
+ checkpointId,
55
+ conversationId,
56
+ throughSeq,
57
+ })),
58
+ };
59
+ for (const entry of entries) {
60
+ const candidateCheckpoint = {
61
+ ...checkpoint,
62
+ entries: [...checkpoint.entries, entry],
63
+ };
64
+ const candidate = {
65
+ ...result,
66
+ checkpoint: candidateCheckpoint,
67
+ omitted: { ...result.omitted, entries: result.omitted.entries - 1 },
68
+ };
69
+ if (JSON.stringify(candidateCheckpoint).length <= Math.floor(maxChars / 2) &&
70
+ JSON.stringify(candidate).length + 1 <= maxChars) {
71
+ checkpoint.entries.push(entry);
72
+ result = candidate;
73
+ }
74
+ }
75
+ for (const event of events) {
76
+ const candidate = {
77
+ ...result,
78
+ events: [...result.events, event],
79
+ omitted: { ...result.omitted, events: result.omitted.events - 1 },
80
+ };
81
+ if (JSON.stringify(candidate).length + 1 <= maxChars)
82
+ result = candidate;
83
+ }
84
+ result.truncated =
85
+ result.truncated &&
86
+ (result.omitted.entries > 0 ||
87
+ result.omitted.events > 0 ||
88
+ result.provenance.omitted === true ||
89
+ Object.keys(result.provenance).length === 0);
90
+ return result;
91
+ }
@@ -0,0 +1,148 @@
1
+ import { randomUUID, randomBytes, createHash, timingSafeEqual, } from "node:crypto";
2
+ import { sessionKeySchema, locationSchema, } from "../../contracts/src/conversations.js";
3
+ export class ConversationStore {
4
+ db;
5
+ constructor(db) {
6
+ this.db = db;
7
+ }
8
+ ensureSession(input, location) {
9
+ const key = sessionKeySchema.parse(input), loc = locationSchema.parse(location);
10
+ this.db.exec("BEGIN IMMEDIATE");
11
+ try {
12
+ const row = this.db
13
+ .prepare("SELECT conversation FROM native_sessions WHERE repo=? AND client=? AND native_id=?")
14
+ .get(key.repoId, key.client, key.nativeSessionId);
15
+ const id = row
16
+ ? String(row.conversation)
17
+ : "conversation:" + randomUUID();
18
+ if (!row) {
19
+ this.db
20
+ .prepare("INSERT INTO conversations VALUES(?,?,?,?,?)")
21
+ .run(key.repoId, id, key.client + " session " + key.nativeSessionId.slice(0, 24), key.client, new Date().toISOString());
22
+ this.db
23
+ .prepare("INSERT INTO native_sessions(repo,client,native_id,conversation,workspace,branch,commit_id) VALUES(?,?,?,?,?,?,?)")
24
+ .run(key.repoId, key.client, key.nativeSessionId, id, loc.workspace, loc.branch ?? null, loc.commit ?? null);
25
+ }
26
+ else
27
+ this.db
28
+ .prepare("UPDATE native_sessions SET workspace=?,branch=?,commit_id=? WHERE repo=? AND client=? AND native_id=?")
29
+ .run(loc.workspace, loc.branch ?? null, loc.commit ?? null, key.repoId, key.client, key.nativeSessionId);
30
+ const conversation = this.get(key.repoId, id);
31
+ this.db.exec("COMMIT");
32
+ return conversation;
33
+ }
34
+ catch (error) {
35
+ this.db.exec("ROLLBACK");
36
+ throw error;
37
+ }
38
+ }
39
+ session(input) {
40
+ const key = sessionKeySchema.parse(input);
41
+ const row = this.db
42
+ .prepare("SELECT conversation FROM native_sessions WHERE repo=? AND client=? AND native_id=?")
43
+ .get(key.repoId, key.client, key.nativeSessionId);
44
+ if (!row)
45
+ throw new Error("Unknown conversation session");
46
+ return this.get(key.repoId, String(row.conversation));
47
+ }
48
+ get(repoId, id) {
49
+ const row = this.db
50
+ .prepare("SELECT * FROM conversations WHERE repo=? AND id=?")
51
+ .get(repoId, id);
52
+ if (!row)
53
+ throw new Error("Unknown conversation in repository");
54
+ return {
55
+ repoId: String(row.repo),
56
+ conversationId: String(row.id),
57
+ title: String(row.title),
58
+ client: String(row.client),
59
+ };
60
+ }
61
+ list(repoId) {
62
+ return this.db
63
+ .prepare("SELECT id FROM conversations WHERE repo=? ORDER BY created DESC,id")
64
+ .all(repoId)
65
+ .map((r) => this.get(repoId, String(r.id)));
66
+ }
67
+ location(key) {
68
+ this.session(key);
69
+ const row = this.db
70
+ .prepare("SELECT workspace,branch,commit_id FROM native_sessions WHERE repo=? AND client=? AND native_id=?")
71
+ .get(key.repoId, key.client, key.nativeSessionId);
72
+ return {
73
+ workspace: String(row.workspace),
74
+ branch: row.branch ? String(row.branch) : undefined,
75
+ commit: row.commit_id ? String(row.commit_id) : undefined,
76
+ };
77
+ }
78
+ issueSessionToken(key) {
79
+ this.session(key);
80
+ const token = randomBytes(32).toString("base64url");
81
+ this.db
82
+ .prepare("UPDATE native_sessions SET token_hash=? WHERE repo=? AND client=? AND native_id=?")
83
+ .run(createHash("sha256").update(token).digest("hex"), key.repoId, key.client, key.nativeSessionId);
84
+ return token;
85
+ }
86
+ assertSessionToken(key, token) {
87
+ this.session(key);
88
+ const row = this.db
89
+ .prepare("SELECT token_hash FROM native_sessions WHERE repo=? AND client=? AND native_id=?")
90
+ .get(key.repoId, key.client, key.nativeSessionId);
91
+ if (!token || token.length > 128 || !row?.token_hash)
92
+ throw new Error("Use the sessionToken from this native session's startup hook");
93
+ const expected = Buffer.from(String(row.token_hash), "hex"), actual = createHash("sha256").update(token).digest();
94
+ if (expected.length !== actual.length || !timingSafeEqual(expected, actual))
95
+ throw new Error("Wrong session capability");
96
+ }
97
+ selectedSource(key) {
98
+ this.session(key);
99
+ const row = this.db
100
+ .prepare("SELECT source,through_seq,checkpoint_seq,source_location FROM continuation_links WHERE repo=? AND client=? AND native_id=?")
101
+ .get(key.repoId, key.client, key.nativeSessionId);
102
+ return row
103
+ ? {
104
+ sourceConversationId: String(row.source),
105
+ throughSeq: Number(row.through_seq),
106
+ checkpointSeq: Number(row.checkpoint_seq),
107
+ location: JSON.parse(String(row.source_location)),
108
+ }
109
+ : null;
110
+ }
111
+ linkSource(key, sourceConversationId) {
112
+ const own = this.session(key);
113
+ this.get(key.repoId, sourceConversationId);
114
+ if (own.conversationId === sourceConversationId)
115
+ throw new Error("Cannot link a conversation to itself");
116
+ this.db.exec("BEGIN IMMEDIATE");
117
+ try {
118
+ const seq = this.db
119
+ .prepare("SELECT COALESCE(MAX(e.seq),0) AS seq FROM events e JOIN conversation_evidence m ON e.repo=m.repo AND e.id=m.event_id WHERE m.repo=? AND m.conversation=?")
120
+ .get(key.repoId, sourceConversationId);
121
+ const revision = this.db
122
+ .prepare("SELECT COALESCE(MAX(seq),0) AS seq FROM checkpoints WHERE repo=? AND conversation=?")
123
+ .get(key.repoId, sourceConversationId);
124
+ const location = this.db
125
+ .prepare("SELECT workspace,branch,commit_id FROM native_sessions WHERE repo=? AND conversation=? LIMIT 1")
126
+ .get(key.repoId, sourceConversationId);
127
+ const frozen = {
128
+ workspace: String(location.workspace),
129
+ ...(location.branch ? { branch: String(location.branch) } : {}),
130
+ ...(location.commit_id ? { commit: String(location.commit_id) } : {}),
131
+ };
132
+ this.db
133
+ .prepare("INSERT INTO continuation_links(repo,client,native_id,source,through_seq,checkpoint_seq,source_location) VALUES(?,?,?,?,?,?,?) ON CONFLICT(repo,client,native_id) DO UPDATE SET source=excluded.source,through_seq=excluded.through_seq,checkpoint_seq=excluded.checkpoint_seq,source_location=excluded.source_location")
134
+ .run(key.repoId, key.client, key.nativeSessionId, sourceConversationId, Number(seq.seq), Number(revision.seq), JSON.stringify(frozen));
135
+ this.db.exec("COMMIT");
136
+ return {
137
+ sourceConversationId,
138
+ throughSeq: Number(seq.seq),
139
+ checkpointSeq: Number(revision.seq),
140
+ location: frozen,
141
+ };
142
+ }
143
+ catch (error) {
144
+ this.db.exec("ROLLBACK");
145
+ throw error;
146
+ }
147
+ }
148
+ }
@@ -0,0 +1,55 @@
1
+ import { chmodSync } from "node:fs";
2
+ import { randomUUID } from "node:crypto";
3
+ export const schemaVersion = 4;
4
+ export function assertSupportedSchema(db) {
5
+ const version = Number(db.prepare("PRAGMA user_version").get().user_version);
6
+ if (version > schemaVersion)
7
+ throw new Error("Unsupported memory schema; use a compatible Knitt runtime");
8
+ return version;
9
+ }
10
+ export function migrate(db) {
11
+ const version = assertSupportedSchema(db);
12
+ if (version === schemaVersion)
13
+ return;
14
+ const file = String(db.prepare("PRAGMA database_list").get().file);
15
+ if (file) {
16
+ const backup = file + ".backup-v" + version + "-" + randomUUID();
17
+ db.exec("VACUUM INTO '" + backup.replaceAll("'", "''") + "'");
18
+ chmodSync(backup, 0o600);
19
+ }
20
+ db.exec("BEGIN IMMEDIATE");
21
+ try {
22
+ // Recheck under the write lock: another process may already have upgraded.
23
+ if (assertSupportedSchema(db) === schemaVersion) {
24
+ db.exec("COMMIT");
25
+ return;
26
+ }
27
+ if (version < 1)
28
+ db.exec(`CREATE TABLE conversations(repo TEXT NOT NULL,id TEXT NOT NULL,title TEXT NOT NULL,client TEXT NOT NULL,created TEXT NOT NULL,PRIMARY KEY(repo,id));
29
+ CREATE TABLE native_sessions(repo TEXT NOT NULL,client TEXT NOT NULL,native_id TEXT NOT NULL,conversation TEXT NOT NULL,workspace TEXT NOT NULL,branch TEXT,commit_id TEXT,PRIMARY KEY(repo,client,native_id));
30
+ CREATE TABLE conversation_evidence(repo TEXT NOT NULL,event_id TEXT NOT NULL,conversation TEXT NOT NULL,PRIMARY KEY(repo,event_id));
31
+ CREATE INDEX conversation_evidence_scope ON conversation_evidence(repo,conversation);
32
+ PRAGMA user_version=1;`);
33
+ if (version < 2)
34
+ db.exec(`CREATE TABLE continuation_links(repo TEXT NOT NULL,client TEXT NOT NULL,native_id TEXT NOT NULL,source TEXT NOT NULL,through_seq INTEGER NOT NULL,PRIMARY KEY(repo,client,native_id)); PRAGMA user_version=2;`);
35
+ if (version < 3)
36
+ db.exec(`CREATE TABLE checkpoints(seq INTEGER PRIMARY KEY AUTOINCREMENT,repo TEXT NOT NULL,conversation TEXT NOT NULL,id TEXT NOT NULL,through_seq INTEGER NOT NULL,payload TEXT NOT NULL,UNIQUE(repo,id)); CREATE INDEX checkpoints_scope ON checkpoints(repo,conversation,seq); PRAGMA user_version=3;`);
37
+ if (version < 4)
38
+ db.exec(`
39
+ ALTER TABLE native_sessions ADD COLUMN token_hash TEXT;
40
+ ALTER TABLE continuation_links ADD COLUMN checkpoint_seq INTEGER NOT NULL DEFAULT 0;
41
+ ALTER TABLE continuation_links ADD COLUMN source_location TEXT NOT NULL DEFAULT '{}';
42
+ CREATE TABLE retired_checkpoint_entries(repo TEXT NOT NULL,conversation TEXT NOT NULL,id TEXT NOT NULL,PRIMARY KEY(repo,conversation,id));
43
+ INSERT OR IGNORE INTO retired_checkpoint_entries
44
+ SELECT checkpoints.repo,checkpoints.conversation,json_extract(entry.value,'$.supersedes')
45
+ FROM checkpoints,json_each(checkpoints.payload,'$.entries') entry
46
+ WHERE json_type(entry.value,'$.supersedes')='text';
47
+ PRAGMA user_version=4;
48
+ `);
49
+ db.exec("COMMIT");
50
+ }
51
+ catch (error) {
52
+ db.exec("ROLLBACK");
53
+ throw error;
54
+ }
55
+ }
@@ -1,10 +1,17 @@
1
+ import { getConversationContext } from "./context.js";
2
+ import { saveCheckpoint, latestCheckpoint } from "./checkpoints.js";
1
3
  import { DatabaseSync } from "node:sqlite";
2
- import { eventSchema, scopeSchema, searchSchema } from "../../contracts/src/events.js";
4
+ import { eventSchema, scopeSchema, searchSchema, } from "../../contracts/src/events.js";
5
+ import { assertSupportedSchema, migrate } from "./migrations.js";
6
+ import { ConversationStore } from "./conversations.js";
3
7
  export class MemoryStore {
4
8
  db;
5
- constructor(path) {
9
+ conversations;
10
+ constructor(path, options = {}) {
6
11
  this.db = new DatabaseSync(path);
7
- this.db.exec(`
12
+ try {
13
+ assertSupportedSchema(this.db);
14
+ this.db.exec(`
8
15
  PRAGMA journal_mode=WAL;
9
16
  PRAGMA busy_timeout=5000;
10
17
  CREATE TABLE IF NOT EXISTS events (
@@ -23,14 +30,142 @@ export class MemoryStore {
23
30
  PRIMARY KEY(repo, session)
24
31
  );
25
32
  `);
33
+ if (options.conversationMode) {
34
+ migrate(this.db);
35
+ this.conversations = new ConversationStore(this.db);
36
+ }
37
+ }
38
+ catch (error) {
39
+ this.db.close();
40
+ throw error;
41
+ }
42
+ }
43
+ conversationStore() {
44
+ if (!this.conversations)
45
+ throw new Error("Enable conversation mode");
46
+ return this.conversations;
47
+ }
48
+ ensureSession(key, location) {
49
+ return this.conversationStore().ensureSession(key, location);
50
+ }
51
+ listConversations(repoId) {
52
+ return this.conversationStore().list(repoId);
53
+ }
54
+ appendEvidence(key, input) {
55
+ const conversation = this.conversationStore().session(key), event = eventSchema.parse(input);
56
+ if (event.repoId !== key.repoId ||
57
+ event.featureId !== conversation.conversationId)
58
+ throw new Error("Evidence belongs to another conversation");
59
+ this.db.exec("BEGIN IMMEDIATE");
60
+ try {
61
+ const prior = this.db
62
+ .prepare("SELECT conversation FROM conversation_evidence WHERE repo=? AND event_id=?")
63
+ .get(key.repoId, event.eventId);
64
+ if (prior && prior.conversation !== conversation.conversationId)
65
+ throw new Error("Evidence belongs to another conversation");
66
+ const existing = this.evidence(key.repoId, event.eventId);
67
+ const withoutProvenance = (value) => JSON.stringify({
68
+ ...value,
69
+ branch: undefined,
70
+ commit: undefined,
71
+ receivedAt: undefined,
72
+ });
73
+ const saved = existing && withoutProvenance(existing) === withoutProvenance(event)
74
+ ? existing
75
+ : this.save(event);
76
+ this.db
77
+ .prepare("INSERT OR IGNORE INTO conversation_evidence VALUES(?,?,?)")
78
+ .run(key.repoId, event.eventId, conversation.conversationId);
79
+ this.db.exec("COMMIT");
80
+ return saved;
81
+ }
82
+ catch (error) {
83
+ this.db.exec("ROLLBACK");
84
+ throw error;
85
+ }
86
+ }
87
+ getConversationContext(key, options) {
88
+ return getConversationContext(this, key, options);
89
+ }
90
+ conversationLocation(repoId, conversationId) {
91
+ this.conversationStore().get(repoId, conversationId);
92
+ const row = this.db
93
+ .prepare("SELECT workspace,branch,commit_id FROM native_sessions WHERE repo=? AND conversation=? LIMIT 1")
94
+ .get(repoId, conversationId);
95
+ return row
96
+ ? {
97
+ workspace: String(row.workspace),
98
+ branch: row.branch ? String(row.branch) : undefined,
99
+ commit: row.commit_id ? String(row.commit_id) : undefined,
100
+ }
101
+ : {};
102
+ }
103
+ saveCheckpoint(key, entries) {
104
+ return saveCheckpoint(this.db, this, key, entries);
105
+ }
106
+ latestCheckpoint(repoId, conversationId, throughSeq, checkpointSeq) {
107
+ this.conversationStore();
108
+ return latestCheckpoint(this.db, repoId, conversationId, throughSeq, checkpointSeq);
109
+ }
110
+ issueSessionToken(key) {
111
+ return this.conversationStore().issueSessionToken(key);
112
+ }
113
+ assertSessionToken(key, token) {
114
+ this.conversationStore().assertSessionToken(key, token);
115
+ }
116
+ sessionConversation(key) {
117
+ return this.conversationStore().session(key);
118
+ }
119
+ sessionLocation(key) {
120
+ return this.conversationStore().location(key);
121
+ }
122
+ linkSource(key, sourceConversationId) {
123
+ return this.conversationStore().linkSource(key, sourceConversationId);
124
+ }
125
+ selectedSource(key) {
126
+ return this.conversationStore().selectedSource(key);
127
+ }
128
+ conversationRows(key) {
129
+ const own = this.sessionConversation(key), source = this.selectedSource(key);
130
+ return this.db
131
+ .prepare(`SELECT e.seq,e.payload,e.received,m.conversation FROM events e JOIN conversation_evidence m ON e.repo=m.repo AND e.id=m.event_id WHERE e.repo=? AND (m.conversation=? OR (m.conversation=? AND e.seq<=?)) ORDER BY e.seq DESC`)
132
+ .all(key.repoId, own.conversationId, source?.sourceConversationId ?? "", source?.throughSeq ?? 0);
133
+ }
134
+ conversationEvidence(key) {
135
+ return this.conversationRows(key).map((row) => ({
136
+ ...JSON.parse(String(row.payload)),
137
+ receivedAt: String(row.received),
138
+ }));
139
+ }
140
+ importLegacyEvidence(key, featureId) {
141
+ const own = this.sessionConversation(key);
142
+ this.db.exec("BEGIN IMMEDIATE");
143
+ try {
144
+ const conflicts = this.db
145
+ .prepare("SELECT 1 FROM events e JOIN conversation_evidence m ON m.repo=e.repo AND m.event_id=e.id WHERE e.repo=? AND e.feature=? AND m.conversation<>? AND json_extract(e.payload,'$.sessionId')=? AND json_extract(e.payload,'$.source') LIKE ? LIMIT 1")
146
+ .get(key.repoId, featureId, own.conversationId, key.nativeSessionId, key.client + ":%");
147
+ if (conflicts)
148
+ throw new Error("Imported evidence belongs to another conversation");
149
+ this.db
150
+ .prepare("INSERT OR IGNORE INTO conversation_evidence SELECT repo,id,? FROM events WHERE repo=? AND feature=? AND json_extract(payload,'$.sessionId')=? AND json_extract(payload,'$.source') LIKE ?")
151
+ .run(own.conversationId, key.repoId, featureId, key.nativeSessionId, key.client + ":%");
152
+ this.db.exec("COMMIT");
153
+ }
154
+ catch (error) {
155
+ this.db.exec("ROLLBACK");
156
+ throw error;
157
+ }
26
158
  }
27
159
  save(input) {
28
160
  const event = eventSchema.parse(input);
29
161
  const payload = JSON.stringify(event);
30
162
  const received = new Date().toISOString();
31
- this.db.prepare("INSERT INTO events(repo,id,feature,branch,payload,received) VALUES(?,?,?,?,?,?) ON CONFLICT(repo,id) DO NOTHING")
163
+ this.db
164
+ .prepare("INSERT INTO events(repo,id,feature,branch,payload,received) VALUES(?,?,?,?,?,?) ON CONFLICT(repo,id) DO NOTHING")
32
165
  .run(event.repoId, event.eventId, event.featureId, event.branch ?? null, payload, received);
33
- const row = this.db.prepare("SELECT payload,received FROM events WHERE repo=? AND id=?").get(event.repoId, event.eventId);
166
+ const row = this.db
167
+ .prepare("SELECT payload,received FROM events WHERE repo=? AND id=?")
168
+ .get(event.repoId, event.eventId);
34
169
  if (row.payload !== payload)
35
170
  throw new Error("Event ID conflict");
36
171
  return { ...event, receivedAt: String(row.received) };
@@ -38,54 +173,97 @@ export class MemoryStore {
38
173
  context(input) {
39
174
  const scope = scopeSchema.parse(input);
40
175
  const where = "repo=? AND feature=?" + (scope.branch ? " AND branch=?" : "");
41
- const params = scope.branch ? [scope.repoId, scope.featureId, scope.branch] : [scope.repoId, scope.featureId];
42
- const count = this.db.prepare("SELECT COUNT(*) AS total FROM events WHERE " + where).get(...params);
43
- const rows = this.db.prepare("SELECT payload,received FROM events WHERE " + where + " ORDER BY seq DESC LIMIT 1000").all(...params);
176
+ const params = scope.branch
177
+ ? [scope.repoId, scope.featureId, scope.branch]
178
+ : [scope.repoId, scope.featureId];
179
+ const count = this.db
180
+ .prepare("SELECT COUNT(*) AS total FROM events WHERE " + where)
181
+ .get(...params);
182
+ const rows = this.db
183
+ .prepare("SELECT payload,received FROM events WHERE " +
184
+ where +
185
+ " ORDER BY seq DESC LIMIT 1000")
186
+ .all(...params);
44
187
  const events = [];
45
188
  let used = 2;
46
189
  for (const row of rows) {
47
- const event = { ...JSON.parse(String(row.payload)), receivedAt: String(row.received) };
190
+ const event = {
191
+ ...JSON.parse(String(row.payload)),
192
+ receivedAt: String(row.received),
193
+ };
48
194
  const size = JSON.stringify(event).length + (events.length ? 1 : 0);
49
195
  if (used + size > scope.maxChars)
50
196
  break;
51
197
  used += size;
52
198
  events.push(event);
53
199
  }
54
- return { events, total: Number(count.total), truncated: events.length < Number(count.total), order: "newest_first", contentTrust: "untrusted_reference" };
200
+ return {
201
+ events,
202
+ total: Number(count.total),
203
+ truncated: events.length < Number(count.total),
204
+ order: "newest_first",
205
+ contentTrust: "untrusted_reference",
206
+ };
55
207
  }
56
208
  evidence(repoId, eventId) {
57
- const row = this.db.prepare("SELECT payload,received FROM events WHERE repo=? AND id=?").get(repoId, eventId);
58
- return row ? { ...JSON.parse(String(row.payload)), receivedAt: String(row.received) } : null;
209
+ const row = this.db
210
+ .prepare("SELECT payload,received FROM events WHERE repo=? AND id=?")
211
+ .get(repoId, eventId);
212
+ return row
213
+ ? { ...JSON.parse(String(row.payload)), receivedAt: String(row.received) }
214
+ : null;
59
215
  }
60
216
  search(input) {
61
217
  const scope = searchSchema.parse(input);
62
- const rows = this.db.prepare("SELECT seq,payload,received FROM events WHERE repo=? AND feature=? AND seq < ? " +
63
- "AND instr(lower(json_extract(payload,'$.content')),lower(?)) > 0 ORDER BY seq DESC LIMIT ?").all(scope.repoId, scope.featureId, scope.before ?? Number.MAX_SAFE_INTEGER, scope.query, scope.limit + 1);
218
+ const rows = this.db
219
+ .prepare("SELECT seq,payload,received FROM events WHERE repo=? AND feature=? AND seq < ? " +
220
+ "AND instr(lower(json_extract(payload,'$.content')),lower(?)) > 0 ORDER BY seq DESC LIMIT ?")
221
+ .all(scope.repoId, scope.featureId, scope.before ?? Number.MAX_SAFE_INTEGER, scope.query, scope.limit + 1);
64
222
  const selected = rows.slice(0, scope.limit);
65
- const matches = selected.map(row => {
223
+ const matches = selected.map((row) => {
66
224
  const event = JSON.parse(String(row.payload));
67
225
  const { content, ...metadata } = event;
68
226
  const match = content.toLowerCase().indexOf(scope.query.toLowerCase());
69
227
  const start = Math.max(0, match - 100);
70
- return { ...metadata, receivedAt: String(row.received), excerpt: content.slice(start, start + 1000) };
228
+ return {
229
+ ...metadata,
230
+ receivedAt: String(row.received),
231
+ excerpt: content.slice(start, start + 1000),
232
+ };
71
233
  });
72
- return { matches, nextCursor: rows.length > scope.limit ? Number(selected[selected.length - 1].seq) : null };
234
+ return {
235
+ matches,
236
+ nextCursor: rows.length > scope.limit
237
+ ? Number(selected[selected.length - 1].seq)
238
+ : null,
239
+ };
73
240
  }
74
241
  createChatSession(repoId, sessionId, owner) {
75
- this.db.prepare("INSERT INTO chat_sessions VALUES(?,?,?)").run(repoId, sessionId, owner);
242
+ this.db
243
+ .prepare("INSERT INTO chat_sessions VALUES(?,?,?)")
244
+ .run(repoId, sessionId, owner);
76
245
  }
77
246
  ownsChatSession(repoId, sessionId, owner) {
78
- return !!this.db.prepare("SELECT 1 FROM chat_sessions WHERE repo=? AND session=? AND owner=?").get(repoId, sessionId, owner);
247
+ return !!this.db
248
+ .prepare("SELECT 1 FROM chat_sessions WHERE repo=? AND session=? AND owner=?")
249
+ .get(repoId, sessionId, owner);
79
250
  }
80
251
  selectSession(repoId, sessionId, featureId, title) {
81
252
  if (!repoId || !sessionId || !featureId)
82
253
  throw new Error("Repository, session and selected feature are required");
83
- this.db.prepare("INSERT INTO session_selections VALUES(?,?,?,?) ON CONFLICT(repo,session) DO UPDATE SET feature=excluded.feature,title=excluded.title")
254
+ this.db
255
+ .prepare("INSERT INTO session_selections VALUES(?,?,?,?) ON CONFLICT(repo,session) DO UPDATE SET feature=excluded.feature,title=excluded.title")
84
256
  .run(repoId, sessionId, featureId, title);
85
257
  }
86
258
  sessionSelection(repoId, sessionId) {
87
- const row = this.db.prepare("SELECT feature,title FROM session_selections WHERE repo=? AND session=?").get(repoId, sessionId);
88
- return row ? { featureId: String(row.feature), title: String(row.title) } : null;
259
+ const row = this.db
260
+ .prepare("SELECT feature,title FROM session_selections WHERE repo=? AND session=?")
261
+ .get(repoId, sessionId);
262
+ return row
263
+ ? { featureId: String(row.feature), title: String(row.title) }
264
+ : null;
265
+ }
266
+ close() {
267
+ this.db.close();
89
268
  }
90
- close() { this.db.close(); }
91
269
  }
@@ -6,7 +6,7 @@ description: Open the shared-memory chat picker and load the conversation the us
6
6
  <!-- shared-agent-memory -->
7
7
  # Continue a chat
8
8
 
9
- Use the native session ID and repository from the memory startup hook. Immediately call shared-memory's choose_conversation with that sessionId. Let the user select a chat in the form. Do not select a chat on their behalf.
9
+ Use the native session ID and repository from the memory startup hook. In local conversation mode, also pass the sessionToken capability from that hook to every memory tool. Never invent or reuse another session capability. Immediately call shared-memory's choose_conversation with that sessionId. Let the user select a chat in the form. Do not select a chat on their behalf.
10
10
 
11
11
  On cancellation, stop. After acceptance, call get_context with the selected repoId and the same sessionId. Briefly show the selected title, last checkpoint and next step. Opening the picker does not authorize file edits.
12
12
 
@@ -0,0 +1,50 @@
1
+ # Local conversation memory preview
2
+
3
+ This opt-in mode separates each coding session's evidence from the source conversation it continues. It remains local to one machine and uses the existing SQLite database, hook delivery queue and MCP server. Legacy connections keep their existing behavior.
4
+
5
+ ## Enable for a connected project
6
+
7
+ Build and pack this checkout, then use that tarball with the installer:
8
+
9
+ ```bash
10
+ npm run check
11
+ npm test
12
+ npm run build
13
+ npm pack
14
+ ```
15
+
16
+ Run the packaged CLI with `setup --workspace /absolute/path/to/project --client codex --client claude-code --capture-new-sessions --package /absolute/path/to/package.tgz --preview`. Review the output, then rerun without `--preview` to apply. `--capture-new-sessions` opts the connected project into capture of supported user/assistant text in fresh sessions; it is retained across subsequent setup/update operations. Select only clients you use. Restart them and approve MCP and hook trust using their normal interfaces.
17
+
18
+ No existing installation is upgraded by building this source. A connection upgrade creates a consistent, private SQLite backup beside an existing database before migrating its schema. New session identity is keyed by repository, coding client and native session ID. Branch and commit are provenance rather than identity.
19
+
20
+ ## Continue work
21
+
22
+ Use `/continue-chat` in a fresh native agent session. The startup hook provides its native session ID and a session capability. Every conversation-mode tool requires both; another known session ID alone grants no access. Capabilities rotate on startup and are stored only as hashes. Pick the source explicitly. The destination keeps its own history; its direct source is limited to the evidence, checkpoint revision and source location available when selected. Canceling preserves the previous link if one exists. Re-selecting refreshes the source cutoff. Ancestors are not recursively recalled.
23
+
24
+ The picker includes stored Knitt conversations and supported local Antigravity, Codex and Claude Code JSONL histories. External discovery reads bounded metadata from known client directories and imports text only after selection. Unsupported metadata and missing directories produce diagnostics. Titles for Codex/Claude discovery currently use the client and native session ID. Clients' local formats can change; fixture support does not establish live support for every release.
25
+
26
+ When MCP form selection is unavailable, use `knitt continue --workspace /absolute/path/to/project --session NATIVE_SESSION_ID --client codex` interactively, with the same `--home` as installation if customized. Use `claude` for Claude Code's native adapter name. The terminal picker requires a session already registered by its startup hook and uses the installation database. It refuses projects that have not opted in and validates session/schema readiness before opening the database for writes. It does not reconfigure the project or launch an agent.
27
+
28
+ ## Checkpoints and evidence
29
+
30
+ Ask the agent to use `save_checkpoint` for goals, decisions, rejected attempts, progress, test claims, blockers and next steps. Every entry requires real evidence IDs accessible to that session. Hooks capture on supported lifecycle invocations, so evidence may not exist until capture runs; use `save_memory` to explicitly record a checkpoint's supporting statement when necessary. Never invent citations.
31
+
32
+ Checkpoints are derived claims, not proof that tests ran. This preview accepts `reported` status and rejects unsupported `verified` claims. The server validates citations and scope but cannot establish semantic truth. Explicit supersession preserves old revisions and original evidence.
33
+
34
+ Recall prioritizes cited checkpoint entries and recent text, with attribution, branch/commit metadata, staleness and omission indicators. The serialized result is bounded to 12000 characters by default (256–24000 configurable); this is not a token count. Very small budgets omit metadata and say so. Search and evidence tools can retrieve older details within the same destination/direct-source scope. Switching sources excludes checkpoint entries whose citations no longer belong to the permitted scope.
35
+
36
+ ## Observe capture
37
+
38
+ `knitt doctor --home /installation/home` reports whether any capture status has been observed, last successful capture/delivery timestamps, per-session queued counts, observed-but-not-yet-captured sessions, partial or unsupported captures, and fixed error codes. It does not log message text. No observation means capture is unknown, not healthy. A missed stop hook cannot be diagnosed at the instant it fails to run; the next invocation or explicit inspection is needed. Queue retries remain invocation-driven, without a background daemon.
39
+
40
+ ## Compatibility and recovery
41
+
42
+ Keep the backup together with its schema version. To restore, first stop all connected servers and hooks; retain the current database and its WAL/SHM files for recovery, then restore a consistent backup through an explicit recovery operation. Restoring a backup discards later changes from the active database; never do this automatically as part of runtime rollback.
43
+
44
+ The updated installer refuses a target runtime whose declared supported schema is older than the database. Missing compatibility metadata means legacy schema zero. Old already-published binaries cannot be retroactively changed: invoking those directly bypasses the new installer's guard. Keep using the compatible installed CLI for update/rollback.
45
+
46
+ The conversation-mode server is for local coding clients. Ordinary-chat/HTTP connectors retain their legacy behavior; this change does not make remote clients conversation-aware.
47
+
48
+ ## Verification
49
+
50
+ Automated tests cover schema preservation/recovery, independent capture, deduplication, explicit selection/cancellation, source cutoffs, checkpoint citations, bounded Unicode recall, capture health and incompatible runtime refusal. Installed-package smoke tests exercise legacy and conversation-mode hooks/MCP, checkpoint handoff, source-history isolation, doctor, update, rollback, failed installation preservation and uninstall. See the implementation progress record for live-client evidence and remaining limits.