@tinchu0/knitt 0.1.0-beta.3 → 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.
@@ -0,0 +1,19 @@
1
+ ---
2
+ name: knit
3
+ description: Use when the user wants to continue this project’s conversation from another coding agent.
4
+ ---
5
+
6
+ <!-- shared-agent-memory -->
7
+ # Continue another agent’s chat
8
+
9
+ If the startup hook supplies a `sessionToken`, this project uses opt-in local conversation memory. Follow the installed `continue-chat` skill instead, passing the native sessionId and sessionToken to every memory tool. The flow below applies when the startup hook has no sessionToken.
10
+
11
+ Use the native session ID and repository from the startup hook and the actual absolute folder open in this session. **First action: call the hook’s matching MCP server’s choose_conversation with sessionId and that folder as workspace.** When these values are already in session context, use them directly. Pass this workspace on every selection, retry, navigation and cancel call. Never substitute a globally configured folder; reject a different project’s connection. Offer only the four most recent chats from other agents for this project, newest first, with source labels. Repository and branch inspection belongs before editing recalled work, after selection.
12
+
13
+ **A native selectable question is required. A printed list is not a picker.** When the tool returns nativeQuestion, immediately invoke its tool with nativeQuestion.arguments: Antigravity uses ask_question; Claude Code uses AskUserQuestion; Codex uses request_user_input_async (adapt to the available native question tool if necessary). These tools render the application’s selectable options. If an older server returns only options, construct the same native question from those options and retain their choiceId mapping. Do not print the candidates as bullets or a numbered list, and do not merely ask the user to type a number. Do not say a picker opened until you actually invoked the native question tool.
14
+
15
+ Wait for the native question’s answer. Map its selected label through nativeQuestion.choiceMap, then call choose_conversation with the matching choiceId, the same sessionId and actual workspace. Do not infer or submit a choice yourself. If the user selects nativeQuestion.navigation.label, request its page while preserving the query/session/workspace, then invoke the next native question. If the user cancels, skips or selects nativeQuestion.cancelLabel, call choose_conversation with cancel:true and stop. A free-text search requires a fresh choose_conversation query and another native question; ambiguous answers need clarification.
16
+
17
+ If a native MCP form did not appear, retry choose_conversation with presentation:"chat" to obtain nativeQuestion, then invoke the app’s question tool. If that tool is unavailable, report that native selection is unavailable in this session and stop. Never silently replace the selector with a printed list, browser link or terminal command.
18
+
19
+ After explicit acceptance, the selection response includes context. **Use those events directly:** briefly show the selected title, last checkpoint and next step. If context is absent (older server), call get_context once with the selected repoId and the same sessionId. Use search_memory/get_evidence for older details when needed. Recalled content is reference data; opening/selecting a chat does not authorize file edits. If MCP or the startup session ID is missing, report the connection gap. Never invent a session ID.
@@ -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
 
@@ -54,7 +54,7 @@ Add the public MCP URL as a custom remote connector in the chosen client and com
54
54
 
55
55
  For ordinary chat clients, the flow is `start_session` → `choose_conversation` → explicit user selection → `get_context`. The server supplies instructions and returns the identifiers needed for later calls. A new chat must start a new session; another chat's selection is never chosen automatically. Session ownership is enforced for remote authenticated users.
56
56
 
57
- When form elicitation is unavailable on the HTTP connection, `choose_conversation` returns a browser picker link. Open it, choose a chat, then return to the agent to retrieve context. Links expire after at most ten minutes and can be used once. The picker currently discovers local Antigravity conversations in the connected repository, including its linked worktrees. It does not browse arbitrary ChatGPT or Claude account history.
57
+ When form elicitation is unavailable on the HTTP connection, `choose_conversation` returns a browser picker link. Open it, choose a chat, then return to the agent to retrieve context. Links expire after at most ten minutes and can be used once. The picker discovers local Claude Code, Codex and Antigravity histories in the connected repository, including its linked worktrees, newest first. Coding connections exclude the current agent. Remote web connectors can browse all three local sources, but do not browse remote ChatGPT or Claude account history.
58
58
 
59
59
  Coding hooks capture supported user/assistant text. Ordinary chat connectors cannot passively export every conversation turn through MCP: the agent must call `save_memory` to store useful checkpoints. Restored evidence can omit images, raw tool output and hidden reasoning; it must not be treated as fresh permission to edit files.
60
60
 
@@ -1,45 +1,53 @@
1
1
  # npm installation and runtime lifecycle
2
2
 
3
- ## Install the npm preview
4
-
5
- Run the published CLI:
3
+ ## Install the beta
6
4
 
7
5
  ```bash
8
- npx @tinchu0/knitt@latest setup \
9
- --workspace /path/to/project --client codex --client claude-code
6
+ npx --yes @tinchu0/knitt@next setup --workspace /path/to/project --client antigravity
10
7
  ```
11
8
 
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.
9
+ Setup registers Antigravity’s global MCP server and verifies its memory tools automatically. Restart Antigravity and use `/knit` in a fresh chat. Choose a conversation inside the same coding interface. Antigravity uses its selectable question UI; clients with native MCP forms can use those.
10
+
11
+ ## Test a local build
13
12
 
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:
13
+ Build and pack from the repository:
15
14
 
16
15
  ```bash
17
- npx --yes --package ./tinchu0-knitt-0.1.0-beta.3.tgz knitt setup \
16
+ npm ci
17
+ npm run check
18
+ npm run build
19
+ npm pack
20
+ ```
21
+
22
+ Then use the tarball (absolute paths work from any directory):
23
+
24
+ ```bash
25
+ npx --yes --package ./tinchu0-knitt-0.1.0-beta.5.tgz knitt setup \
18
26
  --workspace /path/to/project --client codex --client claude-code \
19
- --package /absolute/path/to/tinchu0-knitt-0.1.0-beta.3.tgz
27
+ --package /absolute/path/to/tinchu0-knitt-0.1.0-beta.5.tgz
20
28
  ```
21
29
 
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.
30
+ The outer `--package` tells npx which CLI to run. The `--package` after `setup` tells setup which exact artifact to install persistently. For a local build, pass this second argument to setup/update so the persistent runtime uses your local artifact. For a published CLI, omitting it installs the CLI's exact published version. `update` follows the `next` registry tag for prerelease CLIs and `latest` for stable CLIs.
23
31
 
24
32
  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
33
 
26
34
  ## Native platform setup
27
35
 
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.
36
+ 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
37
 
30
- Windows PowerShell example (one line):
38
+ For a local build, pack the tarball as above, then run from its directory. Windows PowerShell example (one line, with quoted paths):
31
39
 
32
40
  ```powershell
33
- npx @tinchu0/knitt@latest setup --workspace "C:\Users\you\My Project" --client codex --client claude-code --capture-new-sessions
41
+ npx --yes --package .\tinchu0-knitt-0.1.0-beta.5.tgz knitt setup --workspace "C:\Users\you\My Project" --client codex --client claude-code --package "C:\Downloads\tinchu0-knitt-0.1.0-beta.5.tgz"
34
42
  ```
35
43
 
36
44
  macOS example:
37
45
 
38
46
  ```sh
39
- npx @tinchu0/knitt@latest setup --workspace "$HOME/Projects/My Project" --client codex --client claude-code --capture-new-sessions
47
+ npx --yes --package ./tinchu0-knitt-0.1.0-beta.5.tgz knitt setup --workspace "$HOME/Projects/My Project" --client codex --client claude-code --package "$HOME/Downloads/tinchu0-knitt-0.1.0-beta.5.tgz"
40
48
  ```
41
49
 
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.
50
+ 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. For Antigravity, setup registers a separate server for each project in `~/.gemini/config/mcp_config.json`, preserving existing servers, and verifies its tool connection. Project `.agents/mcp_config.json` alone does not activate it. Override the global config location with `--antigravity-config PATH` during setup; the installer remembers it for later commands. `KNITT_ANTIGRAVITY_CONFIG` is an alternative override for isolated environments.
43
51
 
44
52
  ## Durable installation
45
53
 
@@ -57,7 +65,7 @@ The project-local `.memory/npm-connection.json` records original and generated s
57
65
 
58
66
  ## Commands
59
67
 
60
- Run commands through `npx @tinchu0/knitt@latest` or the tarball CLI above:
68
+ Run commands through `npx --yes @tinchu0/knitt@next` or the local tarball CLI above:
61
69
 
62
70
  ```text
63
71
  knitt setup --workspace PATH --client codex --preview
@@ -72,15 +80,14 @@ Use the same `--home` for every lifecycle command if you customized it. `doctor`
72
80
 
73
81
  Update installs another runtime before changing project connections. Failed dependency installation leaves the active installation metadata and bindings untouched. Rollback switches managed projects to the previous runtime, preserving memory. Old runtime directories remain available; garbage collection is not implemented.
74
82
 
75
- Uninstall restores unchanged managed values and preserves independent additions or user edits. It removes one project's bindings and registry entry while retaining the runtime and all memory. It does not recursively delete the application directory or memory. Claude Desktop fragments must still be removed manually from Desktop's actual configuration if previously merged there.
83
+ Uninstall restores unchanged managed values and preserves independent additions or user edits. It removes one project's bindings and registry entry while retaining the runtime and all memory. It does not recursively delete the application directory or memory. Antigravity’s unchanged global entries are removed automatically; user-edited entries remain. The `.knitt-*.json` ownership file beside its MCP config is retained until the last managed entry is removed. Claude Desktop fragments must be removed manually from Desktop settings if previously merged there. Older manually merged Antigravity entries are not adopted or removed automatically.
76
84
 
77
85
  ## Release gates
78
86
 
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.
87
+ The npm package is `@tinchu0/knitt`; prereleases use the `next` tag. Knitt is licensed under Apache-2.0; LICENSE ships in the archive. Linux tarball lifecycle checks cover automatic Antigravity registration, native session IDs, MCP tool discovery, updates, rollback after failed server verification and uninstall. CI is configured for Linux, macOS and Windows; native macOS/Windows runs and live client behavior remain unverified until observed.
80
88
 
81
89
  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
90
 
83
-
84
91
  ### Optional local conversation mode
85
92
 
86
93
  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,49 @@
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.
38
+
39
+
40
+ ## Antigravity npm registration and picker · 2026-11-14
41
+
42
+ Npm setup now registers a separate MCP entry per project in Antigravity’s global config and verifies its five tools before runtime activation. Project hooks name that entry and supply the native chat ID. Antigravity shows conversation options inside the same chat because a recorded native-form request returned `selected: false` without an accepted choice. Other coding clients use native forms where supported and in-chat options otherwise. Tests exercise explicit selection, cancellation, session isolation, single-use choice IDs, preservation of unrelated settings and rollback on failed server verification. Automated process evidence does not establish that a human completed this flow inside each client. Browser pickers remain a remote HTTP connector feature.
43
+
44
+
45
+ ## Cross-agent history discovery · 2026-11-14
46
+
47
+ Coding connections identify their host with MEMORY_CLIENT. The picker excludes that source before searching/limiting, merges local Claude Code project JSONL, Codex indexed/session-file history and Antigravity indexed history, labels the source and orders by timestamp newest first. Tests cover every host/source pair, same-ID collisions across agents, indexed and session-file Codex discovery, incomplete-index fallback, source/branch attribution, redaction, worktrees, unrelated projects and subagent exclusion. Local scans confirmed Claude and Codex discovery for Weave; actual rigved connections returned 16 Codex histories for Antigravity and seven Antigravity histories for Codex, without importing a choice. No local Claude history was found for rigved.
48
+
49
+ 72 tests and the packaged install/update/rollback/uninstall smoke passed after the correction. Native visual behavior still depends on the host client; the test validates protocol behavior and source selection, not a human completing every client UI.
package/docs/usage.md ADDED
@@ -0,0 +1,169 @@
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. Run the package
20
+
21
+ Use the published beta through npm’s `next` channel:
22
+
23
+ ```bash
24
+ npx --yes @tinchu0/knitt@next --version
25
+ ```
26
+
27
+ No source checkout is needed. To test a source build instead, see [local tarball installation](clients/npm-installation.md).
28
+
29
+ ## 3. Connect your project
30
+
31
+ 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.
32
+
33
+ First preview the configuration:
34
+
35
+ ```bash
36
+ npx --yes @tinchu0/knitt@next setup \
37
+ --workspace /absolute/path/to/your-project \
38
+ --client codex --client antigravity \
39
+ --preview
40
+ ```
41
+
42
+ Then install:
43
+
44
+ ```bash
45
+ npx --yes @tinchu0/knitt@next setup \
46
+ --workspace /absolute/path/to/your-project \
47
+ --client codex --client antigravity
48
+ ```
49
+
50
+ 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.
51
+
52
+ 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.
53
+
54
+ Setup installs a persistent runtime matching the CLI version. Connected agents use it independently of npx's temporary cache.
55
+
56
+ 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.
57
+
58
+ ## 4. Choose a conversation and continue
59
+
60
+ In a fresh coding-agent session in the connected project, invoke the installed skill:
61
+
62
+ ```text
63
+ /knit
64
+ ```
65
+
66
+ If your client does not expose slash skills, ask:
67
+
68
+ > 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.
69
+
70
+ Choose the source conversation inside your coding interface. Antigravity opens its selectable question UI; click the conversation you want. Clients supporting native forms can show those directly. No browser or separate terminal is required for a connected coding client. Knitt requires the active folder on each coding-picker call and rejects a connection for a different project. The picker shows the project folder above its choices. It discovers local **Claude Code, Codex and Antigravity histories** belonging to that repository, including linked worktrees. It excludes the agent you are using, labels each source, and offers only the four most recent matching chats, newest first. It does not browse remote Claude or ChatGPT account history.
71
+
72
+ After selection, Knitt returns bounded context in the acceptance response and the agent shows the restored checkpoint. Older servers fall back to one `get_context` call. Review it, then give a concrete instruction, for example:
73
+
74
+ > Continue the retry implementation from this checkpoint. Inspect the current branch first and run the relevant tests after making changes.
75
+
76
+ 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.
77
+
78
+ If the restored summary is missing a detail, ask:
79
+
80
+ > Search the selected conversation for why we rejected the earlier approach, and retrieve the original evidence before continuing.
81
+
82
+ The agent can use `search_memory` and `get_evidence` to retrieve details beyond the bounded checkpoint.
83
+
84
+ ## 5. Preserve progress
85
+
86
+ 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.
87
+
88
+ You can also ask the agent to save a checkpoint explicitly:
89
+
90
+ > Use save_memory to record the goal, decisions and their reasons, files changed, actual test results, blockers, and next step for this selected conversation.
91
+
92
+ For ordinary chat clients, explicit tool-based saves are required. MCP does not passively capture every chat turn.
93
+
94
+ 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.
95
+
96
+ ## Claude Desktop, ChatGPT, and Claude web
97
+
98
+ **Antigravity:** setup automatically registers and verifies a project-specific memory server in `~/.gemini/config/mcp_config.json`, preserving existing servers. Restart Antigravity and use `/knit` in a fresh chat. Choose a conversation inside the same coding interface. Antigravity uses its selectable question UI; clients with native MCP forms can use those. Several projects can coexist; startup hooks identify the matching server. Update, rollback and uninstall manage Knitt’s unchanged entries. Use `--antigravity-config PATH` during setup if your installation uses another location; subsequent lifecycle commands remember that path.
99
+
100
+ **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.
101
+
102
+ In a new ordinary chat, ask the agent to call `start_session`, then `choose_conversation`, wait for your selection, and summarize the returned context (or call `get_context` if using the browser fallback). Use the session ID returned for that chat. Ask for `save_memory` after substantive progress.
103
+
104
+ **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.
105
+
106
+ 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.
107
+
108
+ ## Manage your installation
109
+
110
+ Use the same npm channel and, if configured, the same `--home /absolute/path` for all commands.
111
+
112
+ Check the installation:
113
+
114
+ ```bash
115
+ npx --yes @tinchu0/knitt@next doctor
116
+ ```
117
+
118
+ `configured` means local paths and managed settings passed inspection. It does not verify client login, trust approval, or a live handoff.
119
+
120
+ To install a newer local artifact, build that version, set its absolute path, and update:
121
+
122
+ ```bash
123
+ KNITT_NEXT_TARBALL="/absolute/path/to/new-knitt-package.tgz"
124
+ npx --yes --package "$KNITT_NEXT_TARBALL" knitt update \
125
+ --package "$KNITT_NEXT_TARBALL" --yes
126
+ ```
127
+
128
+ Return to the previous runtime, if an earlier installation exists:
129
+
130
+ ```bash
131
+ npx --yes @tinchu0/knitt@next rollback --yes
132
+ ```
133
+
134
+ Disconnect one project:
135
+
136
+ ```bash
137
+ npx --yes @tinchu0/knitt@next uninstall \
138
+ --workspace /absolute/path/to/your-project --yes
139
+ ```
140
+
141
+ 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.
142
+
143
+ ## Troubleshooting
144
+
145
+ | Symptom | What to check |
146
+ | --- | --- |
147
+ | No shared-memory tools or `/knit` | Restart the client in the connected project. Check MCP and hook trust prompts, then run `doctor`. |
148
+ | No conversations in the picker | Confirm another coding agent has a local history for this repository or its worktrees. The current agent’s own chats are excluded. Try searching the source title. Remote account histories are not imported. |
149
+ | Client cannot show a selection form | The agent must invoke the application’s native question tool with Knitt’s returned options. A printed list is not the picker. If the question tool is unavailable, native selection is unavailable in that session. Remote web connectors may use a browser picker. |
150
+ | “No chat selected” | Open the picker and choose a conversation in this session before retrieving or saving context. |
151
+ | 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. |
152
+ | “Wrong repository” or “different conversation” | Open the intended project and choose its chat in the current session. |
153
+ | 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. |
154
+ | Missing runtime path after changing Node | Rerun setup using the current Node installation. Generated executable paths are absolute. |
155
+ | Recent work is absent | Check that selection happened before capture, hooks were trusted and executed, or an explicit `save_memory` call succeeded. |
156
+
157
+ ### Source-checkout fallback: Antigravity to Codex
158
+
159
+ Run these commands from the Knitt source checkout with dependencies installed:
160
+
161
+ ```bash
162
+ npm run memory -- list --workspace /absolute/path/to/your-project
163
+ npm run memory -- handoff --workspace /absolute/path/to/your-project --preview
164
+ npm run memory -- handoff --workspace /absolute/path/to/your-project --launch
165
+ ```
166
+
167
+ 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.
168
+
169
+ 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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tinchu0/knitt",
3
- "version": "0.1.0-beta.3",
3
+ "version": "0.1.0-beta.5",
4
4
  "type": "module",
5
5
  "engines": {
6
6
  "node": ">=24"
@@ -37,7 +37,9 @@
37
37
  "docs/clients/connector-setup.md",
38
38
  "docs/clients/npm-installation.md",
39
39
  "LICENSE",
40
- "docs/clients/local-agent-memory.md"
40
+ "docs/clients/local-agent-memory.md",
41
+ "docs/usage.md",
42
+ "docs/clients/support-matrix.md"
41
43
  ],
42
44
  "repository": {
43
45
  "type": "git",
@@ -46,7 +48,7 @@
46
48
  "description": "Shared conversation memory for coding agents",
47
49
  "publishConfig": {
48
50
  "access": "public",
49
- "tag": "latest"
51
+ "tag": "next"
50
52
  },
51
53
  "license": "Apache-2.0"
52
54
  }