@tinchu0/knitt 0.1.0-beta.3 → 0.1.0-beta.4

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 (30) hide show
  1. package/README.md +15 -20
  2. package/dist/apps/server/src/server.js +37 -147
  3. package/dist/packages/adapters/src/cli.js +15 -163
  4. package/dist/packages/adapters/src/command.js +18 -149
  5. package/dist/packages/adapters/src/hooks.js +23 -96
  6. package/dist/packages/adapters/src/launch.js +3 -10
  7. package/dist/packages/adapters/src/repository.js +5 -21
  8. package/dist/packages/adapters/src/transcript.js +15 -70
  9. package/dist/packages/installer/src/cli.js +75 -190
  10. package/dist/packages/installer/src/connections.js +79 -196
  11. package/dist/packages/installer/src/runtime.js +37 -94
  12. package/dist/packages/memory/src/store.js +23 -201
  13. package/dist/scripts/connector-setup.js +1 -1
  14. package/dist/skills/{continue-chat → knit}/SKILL.md +2 -2
  15. package/docs/clients/connector-setup.md +1 -1
  16. package/docs/clients/npm-installation.md +17 -22
  17. package/docs/clients/support-matrix.md +37 -0
  18. package/docs/usage.md +179 -0
  19. package/package.json +5 -4
  20. package/dist/apps/server/src/conversation-server.js +0 -203
  21. package/dist/memory-schema.json +0 -1
  22. package/dist/packages/adapters/src/discovery.js +0 -128
  23. package/dist/packages/adapters/src/providers/jsonl.js +0 -105
  24. package/dist/packages/adapters/src/status.js +0 -81
  25. package/dist/packages/contracts/src/conversations.js +0 -30
  26. package/dist/packages/memory/src/checkpoints.js +0 -68
  27. package/dist/packages/memory/src/context.js +0 -91
  28. package/dist/packages/memory/src/conversations.js +0 -148
  29. package/dist/packages/memory/src/migrations.js +0 -55
  30. package/docs/clients/local-agent-memory.md +0 -50
@@ -1,17 +1,10 @@
1
- import { getConversationContext } from "./context.js";
2
- import { saveCheckpoint, latestCheckpoint } from "./checkpoints.js";
3
1
  import { DatabaseSync } from "node:sqlite";
4
- import { eventSchema, scopeSchema, searchSchema, } from "../../contracts/src/events.js";
5
- import { assertSupportedSchema, migrate } from "./migrations.js";
6
- import { ConversationStore } from "./conversations.js";
2
+ import { eventSchema, scopeSchema, searchSchema } from "../../contracts/src/events.js";
7
3
  export class MemoryStore {
8
4
  db;
9
- conversations;
10
- constructor(path, options = {}) {
5
+ constructor(path) {
11
6
  this.db = new DatabaseSync(path);
12
- try {
13
- assertSupportedSchema(this.db);
14
- this.db.exec(`
7
+ this.db.exec(`
15
8
  PRAGMA journal_mode=WAL;
16
9
  PRAGMA busy_timeout=5000;
17
10
  CREATE TABLE IF NOT EXISTS events (
@@ -30,142 +23,14 @@ export class MemoryStore {
30
23
  PRIMARY KEY(repo, session)
31
24
  );
32
25
  `);
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
- }
158
26
  }
159
27
  save(input) {
160
28
  const event = eventSchema.parse(input);
161
29
  const payload = JSON.stringify(event);
162
30
  const received = new Date().toISOString();
163
- this.db
164
- .prepare("INSERT INTO events(repo,id,feature,branch,payload,received) VALUES(?,?,?,?,?,?) ON CONFLICT(repo,id) DO NOTHING")
31
+ this.db.prepare("INSERT INTO events(repo,id,feature,branch,payload,received) VALUES(?,?,?,?,?,?) ON CONFLICT(repo,id) DO NOTHING")
165
32
  .run(event.repoId, event.eventId, event.featureId, event.branch ?? null, payload, received);
166
- const row = this.db
167
- .prepare("SELECT payload,received FROM events WHERE repo=? AND id=?")
168
- .get(event.repoId, event.eventId);
33
+ const row = this.db.prepare("SELECT payload,received FROM events WHERE repo=? AND id=?").get(event.repoId, event.eventId);
169
34
  if (row.payload !== payload)
170
35
  throw new Error("Event ID conflict");
171
36
  return { ...event, receivedAt: String(row.received) };
@@ -173,97 +38,54 @@ export class MemoryStore {
173
38
  context(input) {
174
39
  const scope = scopeSchema.parse(input);
175
40
  const where = "repo=? AND feature=?" + (scope.branch ? " AND branch=?" : "");
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);
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);
187
44
  const events = [];
188
45
  let used = 2;
189
46
  for (const row of rows) {
190
- const event = {
191
- ...JSON.parse(String(row.payload)),
192
- receivedAt: String(row.received),
193
- };
47
+ const event = { ...JSON.parse(String(row.payload)), receivedAt: String(row.received) };
194
48
  const size = JSON.stringify(event).length + (events.length ? 1 : 0);
195
49
  if (used + size > scope.maxChars)
196
50
  break;
197
51
  used += size;
198
52
  events.push(event);
199
53
  }
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
- };
54
+ return { events, total: Number(count.total), truncated: events.length < Number(count.total), order: "newest_first", contentTrust: "untrusted_reference" };
207
55
  }
208
56
  evidence(repoId, eventId) {
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;
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;
215
59
  }
216
60
  search(input) {
217
61
  const scope = searchSchema.parse(input);
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);
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);
222
64
  const selected = rows.slice(0, scope.limit);
223
- const matches = selected.map((row) => {
65
+ const matches = selected.map(row => {
224
66
  const event = JSON.parse(String(row.payload));
225
67
  const { content, ...metadata } = event;
226
68
  const match = content.toLowerCase().indexOf(scope.query.toLowerCase());
227
69
  const start = Math.max(0, match - 100);
228
- return {
229
- ...metadata,
230
- receivedAt: String(row.received),
231
- excerpt: content.slice(start, start + 1000),
232
- };
70
+ return { ...metadata, receivedAt: String(row.received), excerpt: content.slice(start, start + 1000) };
233
71
  });
234
- return {
235
- matches,
236
- nextCursor: rows.length > scope.limit
237
- ? Number(selected[selected.length - 1].seq)
238
- : null,
239
- };
72
+ return { matches, nextCursor: rows.length > scope.limit ? Number(selected[selected.length - 1].seq) : null };
240
73
  }
241
74
  createChatSession(repoId, sessionId, owner) {
242
- this.db
243
- .prepare("INSERT INTO chat_sessions VALUES(?,?,?)")
244
- .run(repoId, sessionId, owner);
75
+ this.db.prepare("INSERT INTO chat_sessions VALUES(?,?,?)").run(repoId, sessionId, owner);
245
76
  }
246
77
  ownsChatSession(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);
78
+ return !!this.db.prepare("SELECT 1 FROM chat_sessions WHERE repo=? AND session=? AND owner=?").get(repoId, sessionId, owner);
250
79
  }
251
80
  selectSession(repoId, sessionId, featureId, title) {
252
81
  if (!repoId || !sessionId || !featureId)
253
82
  throw new Error("Repository, session and selected feature are required");
254
- this.db
255
- .prepare("INSERT INTO session_selections VALUES(?,?,?,?) ON CONFLICT(repo,session) DO UPDATE SET feature=excluded.feature,title=excluded.title")
83
+ this.db.prepare("INSERT INTO session_selections VALUES(?,?,?,?) ON CONFLICT(repo,session) DO UPDATE SET feature=excluded.feature,title=excluded.title")
256
84
  .run(repoId, sessionId, featureId, title);
257
85
  }
258
86
  sessionSelection(repoId, sessionId) {
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();
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;
268
89
  }
90
+ close() { this.db.close(); }
269
91
  }
@@ -30,7 +30,7 @@ try {
30
30
  if (!values.preview)
31
31
  applyConnectionPlan(plan);
32
32
  console.log(client === "claude-code"
33
- ? "Start a fresh Claude Code session in this workspace, approve its MCP connection if prompted, and use /continue-chat."
33
+ ? "Start a fresh Claude Code session in this workspace, approve its MCP connection if prompted, and use /knit."
34
34
  : "Merge the generated .memory/connectors/claude-desktop.json entry into Claude Desktop's local MCP configuration, restart Claude Desktop, then call start_session and choose_conversation.");
35
35
  }
36
36
  else {
@@ -1,12 +1,12 @@
1
1
  ---
2
- name: continue-chat
2
+ name: knit
3
3
  description: Open the shared-memory chat picker and load the conversation the user selects.
4
4
  ---
5
5
 
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. 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.
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.
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
 
@@ -8,7 +8,7 @@ Run commands from the memory product checkout with Node 24+ and dependencies ins
8
8
  npm run connect -- --client claude-code --workspace /path/to/repository
9
9
  ```
10
10
 
11
- This merges project MCP configuration, SessionStart/Stop hooks and the continue-chat skill while preserving unrelated settings. Start a fresh Claude Code session in the target project, log in and approve the project MCP connection. Invoke `/continue-chat`, select a conversation, and review the restored checkpoint before asking for implementation. Capture begins after selection. Hook execution depends on the client's trust settings.
11
+ This merges project MCP configuration, SessionStart/Stop hooks and the knit skill while preserving unrelated settings. Start a fresh Claude Code session in the target project, log in and approve the project MCP connection. Invoke `/knit`, select a conversation, and review the restored checkpoint before asking for implementation. Capture begins after selection. Hook execution depends on the client's trust settings.
12
12
 
13
13
  ## Claude Desktop local MCP
14
14
 
@@ -1,45 +1,45 @@
1
1
  # npm installation and runtime lifecycle
2
2
 
3
- ## Install the npm preview
3
+ ## Try the unpublished release candidate
4
4
 
5
- Run the published CLI:
5
+ Build and pack from the repository:
6
6
 
7
7
  ```bash
8
- npx @tinchu0/knitt@latest setup \
9
- --workspace /path/to/project --client codex --client claude-code
8
+ npm ci
9
+ npm run check
10
+ npm run build
11
+ npm pack
10
12
  ```
11
13
 
12
- Add `--capture-new-sessions` to opt into independent local conversation histories and checkpoint-first handoffs. Version `0.1.0-beta.3` remains a preview. Both `latest` and `next` track the current preview release.
13
-
14
- To test a source checkout before publication, run `npm ci`, `npm run check`, `npm run build` and `npm pack`, then install its exact artifact:
14
+ Then use the tarball (absolute paths work from any directory):
15
15
 
16
16
  ```bash
17
- npx --yes --package ./tinchu0-knitt-0.1.0-beta.3.tgz knitt setup \
17
+ npx --yes --package ./tinchu0-knitt-0.1.0-beta.1.tgz knitt setup \
18
18
  --workspace /path/to/project --client codex --client claude-code \
19
- --package /absolute/path/to/tinchu0-knitt-0.1.0-beta.3.tgz
19
+ --package /absolute/path/to/tinchu0-knitt-0.1.0-beta.1.tgz
20
20
  ```
21
21
 
22
- The outer `--package` selects the CLI; the `--package` after `setup` selects the artifact to install persistently. Without that inner option, setup installs the CLI's exact published version. `update` follows `next` for prerelease CLIs and `latest` for stable CLIs.
22
+ The outer `--package` tells npx which CLI to run. The `--package` after `setup` tells setup which exact artifact to install persistently. Before registry publication this second argument is required for applying setup; preview can run without it. The release candidate is configured for registry publication; until it is published, pass the explicit tarball to setup/update. After publication, omitting the internal package argument installs the CLI's exact published version. `update` follows the `next` registry tag for prerelease CLIs and `latest` for stable CLIs.
23
23
 
24
24
  Use `--preview` to inspect changes without creating installation/configuration files. Interactive setup asks before applying; automation must pass `--yes`. Repeat `--client` for several agents. Setup requires Git repository metadata to derive a stable repository identity.
25
25
 
26
26
  ## Native platform setup
27
27
 
28
- Install Node.js 24+ with npm and Git, and add them to PATH. Windows hooks use built-in Windows PowerShell 5.1 (`powershell.exe` on PATH); no WSL or Python is needed for npm installation. macOS and Linux hooks use their POSIX shell.
28
+ Install Node.js 24+ (including npm) and Git, and ensure both are on PATH. Use the same package on all platforms. Windows hooks use built-in Windows PowerShell 5.1 (`powershell.exe` on PATH); no WSL or Python is needed for npm setup. macOS and Linux hooks use their existing POSIX shell.
29
29
 
30
- Windows PowerShell example (one line):
30
+ Until publication, build the tarball as above, then run from its directory. Windows PowerShell example (one line, with quoted paths):
31
31
 
32
32
  ```powershell
33
- npx @tinchu0/knitt@latest setup --workspace "C:\Users\you\My Project" --client codex --client claude-code --capture-new-sessions
33
+ npx --yes --package .\tinchu0-knitt-0.1.0-beta.1.tgz knitt setup --workspace "C:\Users\you\My Project" --client codex --client claude-code --package "C:\Downloads\tinchu0-knitt-0.1.0-beta.1.tgz"
34
34
  ```
35
35
 
36
36
  macOS example:
37
37
 
38
38
  ```sh
39
- npx @tinchu0/knitt@latest setup --workspace "$HOME/Projects/My Project" --client codex --client claude-code --capture-new-sessions
39
+ npx --yes --package ./tinchu0-knitt-0.1.0-beta.1.tgz knitt setup --workspace "$HOME/Projects/My Project" --client codex --client claude-code --package "$HOME/Downloads/tinchu0-knitt-0.1.0-beta.1.tgz"
40
40
  ```
41
41
 
42
- Existing installations can run `npx @tinchu0/knitt@latest update --yes`. Restart connected agents afterward and approve their normal hook/MCP trust prompts. Update retains memory and the existing capture preference. For Claude Desktop, merge the generated fragment into Desktop settings manually.
42
+ Replace the artifact path with its actual location. The existing lifecycle commands below work on each platform. Restart clients and approve their normal hook/MCP trust prompts. For Claude Desktop, merge the generated fragment into Desktop settings manually.
43
43
 
44
44
  ## Durable installation
45
45
 
@@ -57,7 +57,7 @@ The project-local `.memory/npm-connection.json` records original and generated s
57
57
 
58
58
  ## Commands
59
59
 
60
- Run commands through `npx @tinchu0/knitt@latest` or the tarball CLI above:
60
+ Run commands through the tarball CLI above (or the eventual published package):
61
61
 
62
62
  ```text
63
63
  knitt setup --workspace PATH --client codex --preview
@@ -76,11 +76,6 @@ Uninstall restores unchanged managed values and preserves independent additions
76
76
 
77
77
  ## Release gates
78
78
 
79
- The package is `@tinchu0/knitt`, published under npm account `tinchu0`, with Apache-2.0 licensing. The LICENSE file ships in the npm archive. Release `0.1.0-beta.3` retains opt-in local conversation memory and adds native Windows installation and hooks. Windows npm installation invokes the npm JavaScript entry point directly, keeping package arguments outside a shell. The CI matrix covers Linux, macOS and Windows; live client behavior is separate from packaged lifecycle verification.
79
+ The selected package is `@tinchu0/knitt`, owned by the intended npm account `tinchu0`. A registry lookup returned no public package on 2026-11-13; Terminal login as `tinchu0` is verified. Version `0.1.0-beta.1` is prepared with public access and the `next` tag; actual publication is still pending. Knitt is licensed under Apache-2.0; the LICENSE file ships in the npm package. Native Windows setup now generates Windows PowerShell hooks and launches npm through its JavaScript entry point without interpolating package arguments through a shell. Linux tarball lifecycle checks passed locally. CI is configured for Linux, macOS and Windows; native macOS/Windows runs and live client behavior remain unverified until those checks are observed.
80
80
 
81
81
  ChatGPT, Claude web and teammate machines require a separately reachable authenticated service. Packaging a CLI does not supply hosting, authentication accounts or background synchronization.
82
-
83
-
84
- ### Optional local conversation mode
85
-
86
- Add `--capture-new-sessions` to setup to opt a connected project into independent session capture and explicit continuation links. The preference survives subsequent setup/update operations. Existing connections keep their previous semantics until opted in. This mode upgrades the database using consistent SQLite backups; the updated installer blocks incompatible runtime downgrade rather than restoring data automatically. Use `doctor` for content-free capture status. See [setup and recovery](local-agent-memory.md).
@@ -0,0 +1,37 @@
1
+ # Shared repository memory client evidence · 2026-11-12
2
+
3
+ | Client | MCP path | Capture and recall | Local evidence |
4
+ |---|---|---|---|
5
+ | Claude Desktop, Chat | Generated local stdio fragment or authenticated remote HTTP | Tool-based save/retrieval, explicit session and picker. No passive per-turn capture. | Local fragment generated; application handoff untested. |
6
+ | ChatGPT / Claude web | OAuth Streamable HTTP | Browser picker fallback and scoped checkpoint tools. | Gateway integration-tested; public deployment and OAuth setup pending. |
7
+ | Claude Desktop, local Code session | Claude Code integration | Candidate: Stop hook for capture, SessionStart for recall. Verify both on the desktop build and record trust settings. | Desktop runtime untested. |
8
+ | Claude Code CLI | Explicit MCP configuration | Stop provides session ID, transcript path and final message. Derive repository and branch from hook cwd in an opted-in checkout. | Version 2.1.322 recognizes installed project MCP configuration. Login and MCP approval pending; installer merges hooks and skill in tests. |
9
+ | Codex desktop | Plugin with trusted hooks | SessionStart can direct the agent to retrieve the briefing through MCP. Keep teammate-authored text in tool results because hook additionalContext has developer authority. | Desktop handoff untested. |
10
+ | Codex CLI | stdio or Streamable HTTP; HTTP bearer token can come from an environment variable | Same proposed startup recall as desktop. Validate capture separately before advertising reverse handoff. | Bundled CLI 0.167.0-alpha.3.2 reports stable hooks enabled and both MCP transports in help. |
11
+
12
+ | Antigravity IDE | Custom MCP plus SessionStart/Stop hooks | Capture handles transcriptPath and conversationId. Recall emits injectSteps with an MCP retrieval instruction. | CLI startup hook observed live. Quota blocked assistant response. USER_INPUT format observed; assistant formats fixture-tested. IDE UI handoff untested. |
13
+
14
+ ## Test procedure
15
+
16
+ 1. Use two clean checkouts of the synthetic repository. Associate the branch with retry-import and give the two test identities access to the repository. Supply the fixture facts only to the source client. Keep fixture, logs and source chat out of the receiver's checkout.
17
+ 2. In the ordinary Desktop Chat test, enable the connector once. Discuss the fixture without asking Claude to save it. Inspect the service for attributable writes, including the rejected approach and its reason. If any are missing, record the outcome. Repeat independently in a Desktop Code session using a capture hook.
18
+ 3. Open a fresh Codex session as the second identity and submit only the destination prompt. Check recall against each fixture fact, inspect retrieval logs, and record client versions, repo, branch and manual actions. A manually triggered save or pasted briefing fails the automatic-handoff criterion.
19
+ 4. Control: repeat with memory disabled in a fresh checkout and session. Unexpected knowledge of the fixture invalidates the run. Also repeat on an unrelated feature to check isolation.
20
+
21
+ No end-to-end pass recorded. The hook-based Code path is a candidate for the pilot. Chat remains a separate compatibility target. No user conversation export or account configuration is needed for the fixture itself.
22
+
23
+ Sources: [Claude connectors](https://support.claude.com/en/articles/11176164-use-connectors-to-extend-claude-s-capabilities), [Desktop Code sessions](https://code.claude.com/docs/en/desktop), [Claude Code hooks](https://code.claude.com/docs/en/hooks), [Codex hooks](https://learn.chatgpt.com/docs/hooks), [Codex plugin trust and installation](https://developers.openai.com/plugins/build/plugins).
24
+
25
+ Adapter progress: incremental JSONL capture and a synthetic Antigravity hook-to-MCP handoff pass process integration tests. This is separate from the real two-user pilot above.
26
+
27
+ Live local result: fresh Codex sessions verified automatic Stop capture and startup-driven get_context recall. Both repository hooks were enabled through normal Codex review. Antigravity SessionStart ran, but account quota blocked the model response, so the real cross-agent handoff is pending.
28
+
29
+ ## Installer operating-system evidence · 2026-11-14
30
+
31
+ | Platform | Implementation | Evidence |
32
+ |---|---|---|
33
+ | Linux | POSIX hooks and persistent npm runtime | Local full suite and packaged install, MCP, capture/recall, doctor, update, rollback, failed update and uninstall passed. |
34
+ | macOS | POSIX hooks; Application Support data location | CI configured on macos-latest; native run and live client handoff not observed in this change. |
35
+ | Windows | Native PowerShell hooks; shell-free npm JS entry point; LOCALAPPDATA storage | Windows command generation/npm discovery checked on Linux; CI configured on windows-latest. Native execution and live client handoff not yet observed. |
36
+
37
+ The matrix workflow runs Node.js 24 and Python 3.12. Python is used only by legacy source-installer tests, not the npm runtime. All runners execute type checking, the full suite and the tarball lifecycle smoke test. Configured CI is not evidence that a remote run has passed.
package/docs/usage.md ADDED
@@ -0,0 +1,179 @@
1
+ # How to use Knitt
2
+
3
+ Knitt carries selected conversation context between coding agents working on a Git project. Connect your project, choose the chat you want to continue, review the checkpoint, and tell the destination agent what to do next.
4
+
5
+ For example: discuss a feature in Antigravity, open the same project in Codex, and use Knitt to retrieve the earlier conversation before continuing implementation.
6
+
7
+ ## 1. Prepare your machine
8
+
9
+ You need Node.js **24 or newer**, npm, Git, and a Git project to connect. Check your tools:
10
+
11
+ ```bash
12
+ node --version
13
+ npm --version
14
+ git --version
15
+ ```
16
+
17
+ The installer includes native Linux, macOS and Windows paths. Windows hooks require built-in Windows PowerShell; macOS and Linux use POSIX hooks. Linux checks passed locally; native Windows/macOS runs still need confirmation. Client configuration support does not guarantee that every client has passed a live handoff test. See the [client support evidence](clients/support-matrix.md).
18
+
19
+ ## 2. Build the installation package
20
+
21
+ The repository currently documents Knitt as an unpublished release candidate. Use a locally built tarball for this guide; registry installation is not assumed.
22
+
23
+ From the Knitt source checkout:
24
+
25
+ ```bash
26
+ npm ci
27
+ npm run check
28
+ npm run build
29
+ npm pack
30
+ ```
31
+
32
+ For version `0.1.0-beta.1`, this produces `tinchu0-knitt-0.1.0-beta.1.tgz`. Set its absolute path so the following commands work from any folder:
33
+
34
+ ```bash
35
+ KNITT_TARBALL="/absolute/path/to/knitt/tinchu0-knitt-0.1.0-beta.1.tgz"
36
+ ```
37
+
38
+ Replace the example path with the location printed by `npm pack`. If the package version changes, use the new filename. Keep the tarball available for later management commands.
39
+
40
+ ## 3. Connect your project
41
+
42
+ Replace `/absolute/path/to/your-project` below with the Git repository whose conversations you want to continue. This is your working project, which may be different from the Knitt source checkout.
43
+
44
+ First preview the configuration:
45
+
46
+ ```bash
47
+ npx --yes --package "$KNITT_TARBALL" knitt setup \
48
+ --workspace /absolute/path/to/your-project \
49
+ --client codex --client antigravity \
50
+ --preview
51
+ ```
52
+
53
+ Then install:
54
+
55
+ ```bash
56
+ npx --yes --package "$KNITT_TARBALL" knitt setup \
57
+ --workspace /absolute/path/to/your-project \
58
+ --client codex --client antigravity \
59
+ --package "$KNITT_TARBALL"
60
+ ```
61
+
62
+ Review the displayed changes and confirm in the terminal. For noninteractive setup, add `--yes` after `setup`; the outer `npx --yes` only approves npx's package prompt.
63
+
64
+ Supported `--client` values are `codex`, `claude-code`, `antigravity`, and `claude-desktop`. Repeat the flag for each client you use. Running setup without `--workspace` and `--client` asks for them interactively.
65
+
66
+ The two package arguments have different jobs: npx's `--package` runs the CLI, while setup's `--package` installs that exact artifact as a persistent runtime. Connected agents then use the persistent runtime independently of npx's temporary cache.
67
+
68
+ Restart connected agents, open the target project, and approve their normal MCP and hook trust prompts. Claude Desktop needs an extra manual step described below.
69
+
70
+ ## 4. Choose a conversation and continue
71
+
72
+ In a fresh coding-agent session in the connected project, invoke the installed skill:
73
+
74
+ ```text
75
+ /knit
76
+ ```
77
+
78
+ If your client does not expose slash skills, ask:
79
+
80
+ > Use Knitt's shared-memory connection to open the conversation picker. Let me choose a chat, then retrieve its checkpoint and summarize the last progress and next step.
81
+
82
+ Choose the source conversation in the picker. Knitt's current picker discovers local **Antigravity conversations** belonging to the connected repository, including linked worktrees. It does not browse arbitrary Claude or ChatGPT account history.
83
+
84
+ After selection, the agent calls `get_context` and shows the restored checkpoint. Review it, then give a concrete instruction, for example:
85
+
86
+ > Continue the retry implementation from this checkpoint. Inspect the current branch first and run the relevant tests after making changes.
87
+
88
+ Each new session starts without a selected conversation. Choose explicitly again when opening another session or moving to another connected agent. Canceling the picker leaves the chat unselected.
89
+
90
+ If the restored summary is missing a detail, ask:
91
+
92
+ > Search the selected conversation for why we rejected the earlier approach, and retrieve the original evidence before continuing.
93
+
94
+ The agent can use `search_memory` and `get_evidence` to retrieve details beyond the bounded checkpoint.
95
+
96
+ ## 5. Preserve progress
97
+
98
+ For Codex, Claude Code, and Antigravity, setup installs startup and stop hooks. After conversation selection, supported coding hooks capture available user and assistant text when the client runs them. Capture depends on client support and hook trust; an installed configuration alone does not prove capture is working.
99
+
100
+ You can also ask the agent to save a checkpoint explicitly:
101
+
102
+ > Use save_memory to record the goal, decisions and their reasons, files changed, actual test results, blockers, and next step for this selected conversation.
103
+
104
+ For ordinary chat clients, explicit tool-based saves are required. MCP does not passively capture every chat turn.
105
+
106
+ Checkpoints are reference material: inspect current files and branch state before acting on them. Knitt excludes raw tool results, images, and hidden reasoning. Credential redaction is best effort, so avoid putting secrets in saved text.
107
+
108
+ ## Claude Desktop, ChatGPT, and Claude web
109
+
110
+ **Claude Desktop:** select `--client claude-desktop` during setup. Merge the generated project's `.memory/connectors/claude-desktop.json` `mcpServers` entry into Desktop's local MCP settings, then restart Desktop. Knitt generates the fragment; it does not perform this merge for you.
111
+
112
+ In a new ordinary chat, ask the agent to call `start_session`, then `choose_conversation`, wait for your selection, and call `get_context`. Use the session ID returned for that chat. Ask for `save_memory` after substantive progress.
113
+
114
+ **ChatGPT and Claude web:** require a separately hosted HTTPS MCP endpoint and a compatible OAuth provider. Local CLI setup does not deploy that service. Follow [remote connector setup](clients/connector-setup.md) for profiles, authentication requirements, and browser picker behavior. These clients are not assumed to be live-connected by completing the local quickstart.
115
+
116
+ Local memory lives on one machine. Connecting another machine or using an identical repository name does not synchronize it; team sharing requires a shared authenticated service.
117
+
118
+ ## Manage your installation
119
+
120
+ Use the same tarball CLI and, if configured, the same `--home /absolute/path` for all commands.
121
+
122
+ Check the installation:
123
+
124
+ ```bash
125
+ npx --yes --package "$KNITT_TARBALL" knitt doctor
126
+ ```
127
+
128
+ `configured` means local paths and managed settings passed inspection. It does not verify client login, trust approval, or a live handoff.
129
+
130
+ To install a newer local artifact, build that version, set its absolute path, and update:
131
+
132
+ ```bash
133
+ KNITT_NEXT_TARBALL="/absolute/path/to/new-knitt-package.tgz"
134
+ npx --yes --package "$KNITT_NEXT_TARBALL" knitt update \
135
+ --package "$KNITT_NEXT_TARBALL" --yes
136
+ ```
137
+
138
+ Return to the previous runtime, if an earlier installation exists:
139
+
140
+ ```bash
141
+ npx --yes --package "$KNITT_TARBALL" knitt rollback --yes
142
+ ```
143
+
144
+ Disconnect one project:
145
+
146
+ ```bash
147
+ npx --yes --package "$KNITT_TARBALL" knitt uninstall \
148
+ --workspace /absolute/path/to/your-project --yes
149
+ ```
150
+
151
+ Uninstall restores unchanged managed settings while retaining user edits, the runtime, and memory. If you manually merged a Desktop fragment, remove that entry from Desktop settings yourself. See [installation and lifecycle](clients/npm-installation.md) for storage locations and recovery details.
152
+
153
+ ## Troubleshooting
154
+
155
+ | Symptom | What to check |
156
+ | --- | --- |
157
+ | No shared-memory tools or `/knit` | Restart the client in the connected project. Check MCP and hook trust prompts, then run `doctor`. |
158
+ | No conversations in the picker | Confirm the source chat is a local Antigravity conversation associated with this repository or its worktrees. Try searching its title. Other account histories are not imported. |
159
+ | Client cannot show a selection form | For local Antigravity-to-Codex handoff, use the source-checkout fallback below. Remote HTTP clients may receive a browser picker link instead. |
160
+ | “No chat selected” | Open the picker and choose a conversation in this session before retrieving or saving context. |
161
+ | Missing startup session ID | Reload the project's memory connection and start a fresh session. Ordinary chat clients use `start_session`; do not invent an ID. |
162
+ | “Wrong repository” or “different conversation” | Open the intended project and choose its chat in the current session. |
163
+ | Unmanaged or modified connector conflict | Review the named configuration file. Existing legacy or manually edited settings are not automatically overwritten. See the lifecycle guide before migrating. |
164
+ | Missing runtime path after changing Node | Rerun setup using the current Node installation. Generated executable paths are absolute. |
165
+ | Recent work is absent | Check that selection happened before capture, hooks were trusted and executed, or an explicit `save_memory` call succeeded. |
166
+
167
+ ### Source-checkout fallback: Antigravity to Codex
168
+
169
+ Run these commands from the Knitt source checkout with dependencies installed:
170
+
171
+ ```bash
172
+ npm run memory -- list --workspace /absolute/path/to/your-project
173
+ npm run memory -- handoff --workspace /absolute/path/to/your-project --preview
174
+ npm run memory -- handoff --workspace /absolute/path/to/your-project --launch
175
+ ```
176
+
177
+ The handoff command opens a terminal picker. `--preview` reports the selected handoff without importing or configuring it; `--launch` imports it, configures Codex, and launches Codex in the destination workspace. You can pass `--conversation TITLE_OR_ID` for an explicit selection.
178
+
179
+ This is a separate source-development workflow: it defaults to the checkout's `.memory/events.sqlite`, whereas npm setup uses the persistent installation's data directory. Set `MEMORY_DB` to the intended database if deliberately sharing them. Handoff applies connector settings and may report a conflict with an already managed connection; review that configuration before switching workflows.