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

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 (40) hide show
  1. package/README.md +26 -15
  2. package/dist/apps/server/src/conversation-server.js +203 -0
  3. package/dist/apps/server/src/http-gateway.js +1 -1
  4. package/dist/apps/server/src/main.js +6 -2
  5. package/dist/apps/server/src/server.js +292 -81
  6. package/dist/memory-schema.json +1 -0
  7. package/dist/packages/adapters/src/cli.js +193 -45
  8. package/dist/packages/adapters/src/command.js +149 -18
  9. package/dist/packages/adapters/src/discovery.js +128 -0
  10. package/dist/packages/adapters/src/handoff.js +13 -8
  11. package/dist/packages/adapters/src/histories.js +222 -0
  12. package/dist/packages/adapters/src/history-time.js +10 -0
  13. package/dist/packages/adapters/src/hooks.js +123 -44
  14. package/dist/packages/adapters/src/launch.js +10 -3
  15. package/dist/packages/adapters/src/picker.js +2 -1
  16. package/dist/packages/adapters/src/providers/jsonl.js +105 -0
  17. package/dist/packages/adapters/src/question-ui.js +37 -0
  18. package/dist/packages/adapters/src/repository.js +32 -5
  19. package/dist/packages/adapters/src/scope.js +9 -3
  20. package/dist/packages/adapters/src/server-name.js +6 -0
  21. package/dist/packages/adapters/src/status.js +81 -0
  22. package/dist/packages/adapters/src/transcript.js +72 -15
  23. package/dist/packages/contracts/src/conversations.js +30 -0
  24. package/dist/packages/installer/src/antigravity.js +90 -0
  25. package/dist/packages/installer/src/cli.js +210 -48
  26. package/dist/packages/installer/src/connections.js +193 -38
  27. package/dist/packages/installer/src/runtime.js +73 -11
  28. package/dist/packages/memory/src/checkpoints.js +68 -0
  29. package/dist/packages/memory/src/context.js +91 -0
  30. package/dist/packages/memory/src/conversations.js +148 -0
  31. package/dist/packages/memory/src/migrations.js +55 -0
  32. package/dist/packages/memory/src/store.js +201 -23
  33. package/dist/skills/continue-chat/SKILL.md +15 -0
  34. package/dist/skills/knit/SKILL.md +11 -5
  35. package/docs/clients/connector-setup.md +1 -1
  36. package/docs/clients/local-agent-memory.md +50 -0
  37. package/docs/clients/npm-installation.md +23 -11
  38. package/docs/clients/support-matrix.md +12 -0
  39. package/docs/usage.md +19 -29
  40. package/package.json +5 -4
package/README.md CHANGED
@@ -2,25 +2,25 @@
2
2
 
3
3
  Carry selected repository conversation context between coding agents. Choose the chat you want to continue, retrieve its checkpoint through MCP, and capture new progress using supported coding hooks.
4
4
 
5
- Start with the **[Knitt usage guide](docs/usage.md)** for setup, choosing a conversation, continuing work across agents, saving checkpoints, and troubleshooting.
5
+ ## Installation
6
6
 
7
- ## npm installation (release candidate)
8
-
9
- The npm CLI is being prepared for publication. **It is not published yet:** the selected package is `@tinchu0/knitt`, and terminal login as `tinchu0` is verified. Until then, test the same distribution artifact locally:
7
+ Knitt is published as `@tinchu0/knitt`. Node.js 24+ and Git are required.
10
8
 
11
9
  ```bash
12
- npm ci
13
- npm run build
14
- npm pack
15
- npx --yes --package ./tinchu0-knitt-0.1.0-beta.1.tgz knitt setup \
16
- --package /absolute/path/to/tinchu0-knitt-0.1.0-beta.1.tgz
10
+ npx @tinchu0/knitt@latest setup
17
11
  ```
18
12
 
19
- Setup asks for a Git project folder and agents. It shows configuration changes before applying them, installs a persistent runtime in your user data directory, and leaves client login/trust prompts to the client. Node.js 24+ and Git are required. The npm installation path does not require Python or a source checkout once the tarball exists.
13
+ To enable independent local session capture and checkpoint handoffs for a project:
14
+
15
+ ```bash
16
+ npx @tinchu0/knitt@latest setup \
17
+ --workspace /absolute/path/to/project --client codex --client claude-code \
18
+ --capture-new-sessions
19
+ ```
20
20
 
21
- Once a registry package has actually been published, the intended entry point is `npx @tinchu0/knitt@next setup`. That placeholder is not a current install command.
21
+ Setup shows configuration changes before applying them and installs a persistent runtime in your user data directory. Restart agents and approve their normal MCP/hook trust prompts. The npm installation path does not require Python or a source checkout. Version `0.1.0-beta.3` remains a preview; `latest` and `next` identify the current preview release.
22
22
 
23
- The installer includes native Linux, macOS and Windows paths. Windows uses built-in Windows PowerShell for hooks; macOS and Linux use POSIX hooks. CI is configured to run the full suite and packaged lifecycle checks on all three operating systems. Linux checks passed locally; native Windows/macOS runs and live client handoffs still need confirmation. Claude Desktop currently receives a configuration fragment requiring a manual merge into Desktop settings. No universal client compatibility is claimed.
23
+ The installer includes native Linux, macOS and Windows paths. Windows hooks use built-in Windows PowerShell; macOS and Linux use POSIX hooks. CI runs the full suite and packaged lifecycle checks on all three operating systems. Live application handoffs still require client-specific validation. Claude Desktop currently receives a configuration fragment requiring a manual merge into Desktop settings. No universal client compatibility is claimed.
24
24
 
25
25
  See [npm installation and lifecycle](docs/clients/npm-installation.md) and [remote connector setup](docs/clients/connector-setup.md).
26
26
 
@@ -30,13 +30,13 @@ See [npm installation and lifecycle](docs/clients/npm-installation.md) and [remo
30
30
  - **Claude Desktop:** a generated local MCP fragment; chat checkpoints use tool calls rather than coding hooks.
31
31
  - **ChatGPT / Claude web:** authenticated HTTP MCP is implemented, but requires your own public HTTPS endpoint and compatible OAuth provider. Local CLI setup does not provision a shared server.
32
32
 
33
- The knit skill calls the user picker. New sessions begin unselected. The current history importer discovers local Antigravity conversations in the connected repository, including linked worktrees. It does not access arbitrary Claude or ChatGPT account histories. Ordinary chat MCP clients must explicitly call memory tools to save checkpoints; MCP alone cannot passively capture every chat turn.
33
+ The continue-chat skill calls the user picker. New sessions begin unselected. Legacy connections discover local Antigravity conversations. Opt-in local conversation mode also lists stored Knitt conversations and supported Codex/Claude Code JSONL histories, scoped to the connected repository and linked worktrees. It does not access arbitrary Claude or ChatGPT account histories. Ordinary chat MCP clients must explicitly call memory tools to save checkpoints; MCP alone cannot passively capture every chat turn.
34
34
 
35
35
  Local memory is local to one machine. Team sharing requires a shared authenticated service; identical repository names do not synchronize databases.
36
36
 
37
37
  ## Memory behavior
38
38
 
39
- The tools are `choose_conversation`, `get_context`, `search_memory`, `get_evidence` and `save_memory`; ordinary chat profiles also expose `start_session`. Repository/session checks prevent one session from silently choosing another session's feature. The HTTP gateway validates JWT issuer, audience, expiry, subjects and scopes. Allowed users of a repository service share its feature evidence; finer team roles remain future work.
39
+ The tools are `choose_conversation`, `get_context`, `search_memory`, `get_evidence` and `save_memory`; ordinary chat profiles also expose `start_session`. Local conversation mode additionally exposes `save_checkpoint` and requires the startup-issued session capability. Repository/session checks prevent one session from silently choosing another session's feature. The HTTP gateway validates JWT issuer, audience, expiry, subjects and scopes. Allowed users of a repository service share its feature evidence; finer team roles remain future work.
40
40
 
41
41
  Evidence stores supported user/assistant text, with stable IDs for deduplication. Raw tool results, images and hidden reasoning are excluded. Bounded context reports truncation; search/evidence tools retrieve older detail. Recalled material can be stale or conflicting and is reference material, not authorization to edit files. Basic credential redaction is best effort.
42
42
 
@@ -53,8 +53,19 @@ npm run test:package
53
53
 
54
54
  The legacy Python development installer remains available under `scripts/connect.py`. Published CLI setup and handoff installation use the Node-only planner.
55
55
 
56
- This repository remains a release candidate. Public release additionally requires publisher access confirmation, a full-history/private-data audit and supported-platform evidence. No npm publication or repository visibility change is performed by building or packing.
56
+ Knitt remains a preview. Automated and installed-package checks do not establish live compatibility with every client or platform. Building or packing alone does not publish to npm.
57
57
 
58
58
  ## License
59
59
 
60
60
  Knitt is licensed under the [Apache License 2.0](LICENSE).
61
+
62
+
63
+ ## Local conversation memory preview
64
+
65
+ Opt-in `setup --capture-new-sessions` adds independent coding-session histories, explicit continuation links and cited checkpoint-first recall. Existing connections remain compatible. See [local memory setup and recovery](docs/clients/local-agent-memory.md).
66
+
67
+ ## Cross-agent continuation
68
+
69
+ Use `/knit` to choose one of the four most recent chats from other coding agents in the current project. The native picker preserves explicit selection and returns bounded context with acceptance, avoiding an extra context tool call. Search by title to find older chats.
70
+
71
+ See [the usage guide](docs/usage.md) for setup and supported clients. Existing opt-in local memory, checkpoints and evidence retrieval remain available through `/continue-chat`; that mode keeps its capability-scoped picker and context flow.
@@ -0,0 +1,203 @@
1
+ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
2
+ import { z } from "zod";
3
+ import { mkdirSync } from "node:fs";
4
+ import { dirname, join } from "node:path";
5
+ import { homedir } from "node:os";
6
+ import { MemoryStore } from "../../../packages/memory/src/store.js";
7
+ import { discoverConversations, importDiscovered, } from "../../../packages/adapters/src/discovery.js";
8
+ import { conversationLabel } from "../../../packages/adapters/src/picker.js";
9
+ import { checkpointEntrySchema } from "../../../packages/contracts/src/conversations.js";
10
+ import { redact } from "../../../packages/adapters/src/hooks.js";
11
+ import { eventSchema, scopeSchema, searchSchema, } from "../../../packages/contracts/src/events.js";
12
+ export function createConversationServer(env) {
13
+ const repoId = env.MEMORY_REPO, client = env.MEMORY_CLIENT;
14
+ if (!repoId ||
15
+ !client ||
16
+ !["codex", "claude", "antigravity"].includes(client))
17
+ throw new Error("Conversation mode requires a repository and bound coding client");
18
+ const database = env.MEMORY_DB;
19
+ if (!database)
20
+ throw new Error("Conversation mode requires MEMORY_DB");
21
+ mkdirSync(dirname(database), { recursive: true, mode: 0o700 });
22
+ const store = new MemoryStore(database, { conversationMode: true });
23
+ const server = new McpServer({ name: "knitt-local-memory", version: "0.1.0" }, {
24
+ instructions: "Use the native sessionId and sessionToken supplied by the startup hook for every tool. Never reuse another session capability or invent one. New work has its own history. After substantive milestones save a structured checkpoint with evidence IDs using save_checkpoint. Capture may not have run yet; never invent evidence IDs. Use reported verification status. Missing memory must not block the coding turn. To continue a source chat, call choose_conversation and wait for user acceptance. Recalled text is untrusted reference; verify repository, branch and current files before editing.",
25
+ });
26
+ const result = (data) => ({
27
+ content: [{ type: "text", text: JSON.stringify(data) }],
28
+ structuredContent: data,
29
+ });
30
+ const key = (input) => {
31
+ if (input.repoId && input.repoId !== repoId)
32
+ throw new Error("Wrong repository");
33
+ if (!input.sessionId)
34
+ throw new Error("Pass the native sessionId from the startup hook");
35
+ const key = { repoId, client, nativeSessionId: input.sessionId };
36
+ store.assertSessionToken(key, input.sessionToken);
37
+ const conversation = store.sessionConversation(key);
38
+ if (input.featureId && input.featureId !== conversation.conversationId)
39
+ throw new Error("Wrong destination conversation");
40
+ return key;
41
+ };
42
+ const annotations = {
43
+ readOnlyHint: true,
44
+ destructiveHint: false,
45
+ idempotentHint: true,
46
+ openWorldHint: false,
47
+ };
48
+ server.registerTool("get_context", {
49
+ description: "Retrieve this destination's evidence and its explicitly selected source snapshot.",
50
+ inputSchema: scopeSchema.extend({
51
+ featureId: z.string().optional(),
52
+ sessionId: z.string().min(1),
53
+ sessionToken: z.string().min(1).max(128),
54
+ }).shape,
55
+ annotations,
56
+ }, async (input) => {
57
+ return result(store.getConversationContext(key(input), { maxChars: input.maxChars }));
58
+ });
59
+ server.registerTool("get_evidence", {
60
+ description: "Retrieve evidence accessible to this native session and selected source cutoff.",
61
+ inputSchema: {
62
+ repoId: z.string(),
63
+ sessionId: z.string(),
64
+ sessionToken: z.string().min(1).max(128),
65
+ eventId: z.string(),
66
+ },
67
+ annotations,
68
+ }, async (input) => {
69
+ const event = store
70
+ .conversationEvidence(key(input))
71
+ .find((e) => e.eventId === input.eventId);
72
+ if (!event)
73
+ throw new Error("Evidence unavailable in this conversation");
74
+ return result({ event });
75
+ });
76
+ server.registerTool("search_memory", {
77
+ description: "Search destination and selected source evidence. Use nextCursor as before to page.",
78
+ inputSchema: searchSchema.extend({
79
+ featureId: z.string().optional(),
80
+ sessionId: z.string(),
81
+ sessionToken: z.string().min(1).max(128),
82
+ }).shape,
83
+ annotations,
84
+ }, async (input) => {
85
+ const rows = store.conversationRows(key(input)).filter((row) => Number(row.seq) < (input.before ?? Number.MAX_SAFE_INTEGER) &&
86
+ String(JSON.parse(String(row.payload)).content)
87
+ .toLowerCase()
88
+ .includes(input.query.toLowerCase()));
89
+ const selected = rows.slice(0, input.limit);
90
+ return result({
91
+ matches: selected.map((row) => {
92
+ const event = eventSchema.parse(JSON.parse(String(row.payload)));
93
+ const { content, ...metadata } = event;
94
+ const start = Math.max(0, content.toLowerCase().indexOf(input.query.toLowerCase()) - 100);
95
+ return { ...metadata, excerpt: content.slice(start, start + 1000) };
96
+ }),
97
+ nextCursor: rows.length > input.limit ? Number(selected.at(-1).seq) : null,
98
+ });
99
+ });
100
+ server.registerTool("save_memory", {
101
+ description: "Save redacted evidence into the current destination conversation.",
102
+ inputSchema: eventSchema.extend({
103
+ featureId: z.string().optional(),
104
+ sessionId: z.string(),
105
+ sessionToken: z.string().min(1).max(128),
106
+ }).shape,
107
+ annotations: { ...annotations, readOnlyHint: false },
108
+ }, async (input) => {
109
+ const session = key(input), conversation = store.sessionConversation(session);
110
+ const { sessionToken, ...evidence } = input;
111
+ return result({
112
+ event: store.appendEvidence(session, {
113
+ ...evidence,
114
+ featureId: conversation.conversationId,
115
+ content: redact(input.content),
116
+ }),
117
+ });
118
+ });
119
+ server.registerTool("save_checkpoint", {
120
+ description: "Save goals, decisions, failed attempts, verification claims and next steps with evidence IDs. Use reported status; test claims are not verified execution.",
121
+ inputSchema: {
122
+ repoId: z.string(),
123
+ sessionId: z.string(),
124
+ sessionToken: z.string().min(1).max(128),
125
+ entries: z.array(checkpointEntrySchema).min(1).max(100),
126
+ },
127
+ annotations: { ...annotations, readOnlyHint: false },
128
+ }, async (input) => result({ checkpoint: store.saveCheckpoint(key(input), input.entries) }));
129
+ server.registerTool("choose_conversation", {
130
+ description: "Ask the USER which local conversation to continue. Never select on their behalf.",
131
+ inputSchema: {
132
+ sessionId: z.string(),
133
+ sessionToken: z.string().min(1).max(128),
134
+ query: z.string().max(256).default(""),
135
+ },
136
+ annotations: { ...annotations, readOnlyHint: false },
137
+ }, async (input) => {
138
+ const session = key(input), own = store.sessionConversation(session);
139
+ const discovery = discoverConversations(store, repoId, env.MEMORY_WORKSPACE ?? process.cwd(), {
140
+ codex: env.MEMORY_CODEX_HISTORY ?? join(homedir(), ".codex/sessions"),
141
+ claude: env.MEMORY_CLAUDE_HISTORY ?? join(homedir(), ".claude/projects"),
142
+ antigravity: env.MEMORY_SOURCE_ROOTS
143
+ ? z.array(z.string()).parse(JSON.parse(env.MEMORY_SOURCE_ROOTS))
144
+ : ["antigravity", "antigravity-cli", "antigravity-ide"].map((n) => join(homedir(), ".gemini", n)),
145
+ });
146
+ const conversations = discovery.conversations
147
+ .filter((c) => c.storedId !== own.conversationId &&
148
+ !(c.client === client && c.sourceId === session.nativeSessionId) &&
149
+ conversationLabel(c)
150
+ .toLowerCase()
151
+ .includes(input.query.toLowerCase()))
152
+ .slice(0, 50);
153
+ if (!conversations.length)
154
+ return result({
155
+ selectionRequired: true,
156
+ message: "No matching local conversations",
157
+ diagnostics: discovery.diagnostics,
158
+ });
159
+ if (!server.server.getClientCapabilities()?.elicitation?.form)
160
+ return result({
161
+ selectionRequired: true,
162
+ message: "Use the terminal conversation picker: knitt continue --workspace PATH --session NATIVE_SESSION_ID --client " +
163
+ client,
164
+ diagnostics: discovery.diagnostics,
165
+ });
166
+ const choice = await server.server.elicitInput({
167
+ mode: "form",
168
+ message: "Which conversation do you want to continue?",
169
+ requestedSchema: {
170
+ type: "object",
171
+ properties: {
172
+ conversation: {
173
+ type: "string",
174
+ oneOf: conversations.map((c, i) => ({
175
+ const: String(i),
176
+ title: conversationLabel(c),
177
+ })),
178
+ },
179
+ },
180
+ required: ["conversation"],
181
+ },
182
+ });
183
+ if (choice.action !== "accept")
184
+ return result({ selected: false, selectionRequired: true });
185
+ const index = choice.content?.conversation;
186
+ if (typeof index !== "string" ||
187
+ !/^(0|[1-9][0-9]*)$/.test(index) ||
188
+ !conversations[Number(index)])
189
+ throw new Error("Choose a displayed conversation");
190
+ const source = conversations[Number(index)];
191
+ const sourceId = importDiscovered(store, repoId, source, join(dirname(database), "history-import"));
192
+ const link = store.linkSource(session, sourceId);
193
+ return result({
194
+ selected: true,
195
+ repoId,
196
+ sessionId: input.sessionId,
197
+ ...link,
198
+ title: source.title,
199
+ conversationId: own.conversationId,
200
+ });
201
+ });
202
+ return { server, store, close: () => store.close() };
203
+ }
@@ -84,7 +84,7 @@ export function createGateway(options) {
84
84
  }
85
85
  const memory = createMemoryServer({
86
86
  MEMORY_DB: options.database, MEMORY_REPO: options.repoId, MEMORY_WORKSPACE: options.workspace,
87
- MEMORY_SESSION_SELECTION: "1",
87
+ MEMORY_SESSION_SELECTION: "1", MEMORY_CLIENT: "web",
88
88
  ...(options.sourceRoots ? { MEMORY_SOURCE_ROOTS: JSON.stringify(options.sourceRoots) } : {}),
89
89
  }, {
90
90
  ownerId, canWrite: req.auth.scopes.includes("memory:write"),
@@ -1,7 +1,10 @@
1
1
  import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
2
2
  import { createMemoryServer } from "./server.js";
3
- const app = createMemoryServer(process.env, process.env.MEMORY_CHAT_CLIENT
4
- ? { ownerId: "local:" + process.env.MEMORY_CHAT_CLIENT } : {});
3
+ const ownerId = process.env.MEMORY_CHAT_CLIENT ? 'local:' + process.env.MEMORY_CHAT_CLIENT : undefined;
4
+ const app = createMemoryServer(process.env, {
5
+ ...(ownerId ? { ownerId } : {}), inChatPicker: true,
6
+ preferChatPicker: ['chat', 'native_question'].includes(process.env.MEMORY_PICKER_MODE ?? ''),
7
+ });
5
8
  await app.server.connect(new StdioServerTransport());
6
9
  let closing = false;
7
10
  async function shutdown() {
@@ -13,3 +16,4 @@ async function shutdown() {
13
16
  }
14
17
  process.on("SIGINT", () => { void shutdown(); });
15
18
  process.on("SIGTERM", () => { void shutdown(); });
19
+ process.stdin.on('end', () => { void shutdown(); });