@tinchu0/knitt 0.1.0-beta.1 → 0.1.0-beta.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +20 -13
- package/dist/apps/server/src/conversation-server.js +203 -0
- package/dist/apps/server/src/server.js +147 -37
- package/dist/memory-schema.json +1 -0
- package/dist/packages/adapters/src/cli.js +163 -15
- package/dist/packages/adapters/src/command.js +149 -18
- package/dist/packages/adapters/src/discovery.js +128 -0
- package/dist/packages/adapters/src/hooks.js +96 -23
- package/dist/packages/adapters/src/launch.js +10 -3
- package/dist/packages/adapters/src/providers/jsonl.js +105 -0
- package/dist/packages/adapters/src/repository.js +21 -5
- package/dist/packages/adapters/src/status.js +81 -0
- package/dist/packages/adapters/src/transcript.js +70 -15
- package/dist/packages/contracts/src/conversations.js +30 -0
- package/dist/packages/installer/src/cli.js +190 -75
- package/dist/packages/installer/src/connections.js +198 -83
- package/dist/packages/installer/src/platform.js +55 -0
- package/dist/packages/installer/src/runtime.js +94 -37
- package/dist/packages/memory/src/checkpoints.js +68 -0
- package/dist/packages/memory/src/context.js +91 -0
- package/dist/packages/memory/src/conversations.js +148 -0
- package/dist/packages/memory/src/migrations.js +55 -0
- package/dist/packages/memory/src/store.js +201 -23
- package/dist/skills/continue-chat/SKILL.md +1 -1
- package/docs/clients/local-agent-memory.md +50 -0
- package/docs/clients/npm-installation.md +37 -13
- package/package.json +4 -3
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
# Local conversation memory preview
|
|
2
|
+
|
|
3
|
+
This opt-in mode separates each coding session's evidence from the source conversation it continues. It remains local to one machine and uses the existing SQLite database, hook delivery queue and MCP server. Legacy connections keep their existing behavior.
|
|
4
|
+
|
|
5
|
+
## Enable for a connected project
|
|
6
|
+
|
|
7
|
+
Build and pack this checkout, then use that tarball with the installer:
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
npm run check
|
|
11
|
+
npm test
|
|
12
|
+
npm run build
|
|
13
|
+
npm pack
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
Run the packaged CLI with `setup --workspace /absolute/path/to/project --client codex --client claude-code --capture-new-sessions --package /absolute/path/to/package.tgz --preview`. Review the output, then rerun without `--preview` to apply. `--capture-new-sessions` opts the connected project into capture of supported user/assistant text in fresh sessions; it is retained across subsequent setup/update operations. Select only clients you use. Restart them and approve MCP and hook trust using their normal interfaces.
|
|
17
|
+
|
|
18
|
+
No existing installation is upgraded by building this source. A connection upgrade creates a consistent, private SQLite backup beside an existing database before migrating its schema. New session identity is keyed by repository, coding client and native session ID. Branch and commit are provenance rather than identity.
|
|
19
|
+
|
|
20
|
+
## Continue work
|
|
21
|
+
|
|
22
|
+
Use `/continue-chat` in a fresh native agent session. The startup hook provides its native session ID and a session capability. Every conversation-mode tool requires both; another known session ID alone grants no access. Capabilities rotate on startup and are stored only as hashes. Pick the source explicitly. The destination keeps its own history; its direct source is limited to the evidence, checkpoint revision and source location available when selected. Canceling preserves the previous link if one exists. Re-selecting refreshes the source cutoff. Ancestors are not recursively recalled.
|
|
23
|
+
|
|
24
|
+
The picker includes stored Knitt conversations and supported local Antigravity, Codex and Claude Code JSONL histories. External discovery reads bounded metadata from known client directories and imports text only after selection. Unsupported metadata and missing directories produce diagnostics. Titles for Codex/Claude discovery currently use the client and native session ID. Clients' local formats can change; fixture support does not establish live support for every release.
|
|
25
|
+
|
|
26
|
+
When MCP form selection is unavailable, use `knitt continue --workspace /absolute/path/to/project --session NATIVE_SESSION_ID --client codex` interactively, with the same `--home` as installation if customized. Use `claude` for Claude Code's native adapter name. The terminal picker requires a session already registered by its startup hook and uses the installation database. It refuses projects that have not opted in and validates session/schema readiness before opening the database for writes. It does not reconfigure the project or launch an agent.
|
|
27
|
+
|
|
28
|
+
## Checkpoints and evidence
|
|
29
|
+
|
|
30
|
+
Ask the agent to use `save_checkpoint` for goals, decisions, rejected attempts, progress, test claims, blockers and next steps. Every entry requires real evidence IDs accessible to that session. Hooks capture on supported lifecycle invocations, so evidence may not exist until capture runs; use `save_memory` to explicitly record a checkpoint's supporting statement when necessary. Never invent citations.
|
|
31
|
+
|
|
32
|
+
Checkpoints are derived claims, not proof that tests ran. This preview accepts `reported` status and rejects unsupported `verified` claims. The server validates citations and scope but cannot establish semantic truth. Explicit supersession preserves old revisions and original evidence.
|
|
33
|
+
|
|
34
|
+
Recall prioritizes cited checkpoint entries and recent text, with attribution, branch/commit metadata, staleness and omission indicators. The serialized result is bounded to 12000 characters by default (256–24000 configurable); this is not a token count. Very small budgets omit metadata and say so. Search and evidence tools can retrieve older details within the same destination/direct-source scope. Switching sources excludes checkpoint entries whose citations no longer belong to the permitted scope.
|
|
35
|
+
|
|
36
|
+
## Observe capture
|
|
37
|
+
|
|
38
|
+
`knitt doctor --home /installation/home` reports whether any capture status has been observed, last successful capture/delivery timestamps, per-session queued counts, observed-but-not-yet-captured sessions, partial or unsupported captures, and fixed error codes. It does not log message text. No observation means capture is unknown, not healthy. A missed stop hook cannot be diagnosed at the instant it fails to run; the next invocation or explicit inspection is needed. Queue retries remain invocation-driven, without a background daemon.
|
|
39
|
+
|
|
40
|
+
## Compatibility and recovery
|
|
41
|
+
|
|
42
|
+
Keep the backup together with its schema version. To restore, first stop all connected servers and hooks; retain the current database and its WAL/SHM files for recovery, then restore a consistent backup through an explicit recovery operation. Restoring a backup discards later changes from the active database; never do this automatically as part of runtime rollback.
|
|
43
|
+
|
|
44
|
+
The updated installer refuses a target runtime whose declared supported schema is older than the database. Missing compatibility metadata means legacy schema zero. Old already-published binaries cannot be retroactively changed: invoking those directly bypasses the new installer's guard. Keep using the compatible installed CLI for update/rollback.
|
|
45
|
+
|
|
46
|
+
The conversation-mode server is for local coding clients. Ordinary-chat/HTTP connectors retain their legacy behavior; this change does not make remote clients conversation-aware.
|
|
47
|
+
|
|
48
|
+
## Verification
|
|
49
|
+
|
|
50
|
+
Automated tests cover schema preservation/recovery, independent capture, deduplication, explicit selection/cancellation, source cutoffs, checkpoint citations, bounded Unicode recall, capture health and incompatible runtime refusal. Installed-package smoke tests exercise legacy and conversation-mode hooks/MCP, checkpoint handoff, source-history isolation, doctor, update, rollback, failed installation preservation and uninstall. See the implementation progress record for live-client evidence and remaining limits.
|
|
@@ -1,34 +1,53 @@
|
|
|
1
1
|
# npm installation and runtime lifecycle
|
|
2
2
|
|
|
3
|
-
##
|
|
3
|
+
## Install the npm preview
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Run the published CLI:
|
|
6
6
|
|
|
7
7
|
```bash
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
npm run build
|
|
11
|
-
npm pack
|
|
8
|
+
npx @tinchu0/knitt@latest setup \
|
|
9
|
+
--workspace /path/to/project --client codex --client claude-code
|
|
12
10
|
```
|
|
13
11
|
|
|
14
|
-
|
|
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:
|
|
15
15
|
|
|
16
16
|
```bash
|
|
17
|
-
npx --yes --package ./tinchu0-knitt-0.1.0-beta.
|
|
17
|
+
npx --yes --package ./tinchu0-knitt-0.1.0-beta.3.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.
|
|
19
|
+
--package /absolute/path/to/tinchu0-knitt-0.1.0-beta.3.tgz
|
|
20
20
|
```
|
|
21
21
|
|
|
22
|
-
The outer `--package`
|
|
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.
|
|
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
|
+
## Native platform setup
|
|
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.
|
|
29
|
+
|
|
30
|
+
Windows PowerShell example (one line):
|
|
31
|
+
|
|
32
|
+
```powershell
|
|
33
|
+
npx @tinchu0/knitt@latest setup --workspace "C:\Users\you\My Project" --client codex --client claude-code --capture-new-sessions
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
macOS example:
|
|
37
|
+
|
|
38
|
+
```sh
|
|
39
|
+
npx @tinchu0/knitt@latest setup --workspace "$HOME/Projects/My Project" --client codex --client claude-code --capture-new-sessions
|
|
40
|
+
```
|
|
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.
|
|
43
|
+
|
|
26
44
|
## Durable installation
|
|
27
45
|
|
|
28
46
|
The default installation directory is:
|
|
29
47
|
|
|
30
48
|
- Linux: `$XDG_DATA_HOME/shared-agent-memory` or `~/.local/share/shared-agent-memory`.
|
|
31
|
-
- macOS: `~/Library/Application Support/SharedAgentMemory
|
|
49
|
+
- macOS: `~/Library/Application Support/SharedAgentMemory`.
|
|
50
|
+
- Windows: `%LOCALAPPDATA%\SharedAgentMemory`, falling back to `~\AppData\Local\SharedAgentMemory`.
|
|
32
51
|
|
|
33
52
|
Override with `SHARED_MEMORY_HOME` or `--home /absolute/path`. The directory contains private `data/`, versioned runtime installations and `installation.json`. Node and runtime paths in generated settings are absolute. Upgrading/removing Node itself can invalidate the executable path; rerun setup with the new Node installation.
|
|
34
53
|
|
|
@@ -38,7 +57,7 @@ The project-local `.memory/npm-connection.json` records original and generated s
|
|
|
38
57
|
|
|
39
58
|
## Commands
|
|
40
59
|
|
|
41
|
-
Run commands through
|
|
60
|
+
Run commands through `npx @tinchu0/knitt@latest` or the tarball CLI above:
|
|
42
61
|
|
|
43
62
|
```text
|
|
44
63
|
knitt setup --workspace PATH --client codex --preview
|
|
@@ -57,6 +76,11 @@ Uninstall restores unchanged managed values and preserves independent additions
|
|
|
57
76
|
|
|
58
77
|
## Release gates
|
|
59
78
|
|
|
60
|
-
The
|
|
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.
|
|
61
80
|
|
|
62
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).
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@tinchu0/knitt",
|
|
3
|
-
"version": "0.1.0-beta.
|
|
3
|
+
"version": "0.1.0-beta.3",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"engines": {
|
|
6
6
|
"node": ">=24"
|
|
@@ -36,7 +36,8 @@
|
|
|
36
36
|
"README.md",
|
|
37
37
|
"docs/clients/connector-setup.md",
|
|
38
38
|
"docs/clients/npm-installation.md",
|
|
39
|
-
"LICENSE"
|
|
39
|
+
"LICENSE",
|
|
40
|
+
"docs/clients/local-agent-memory.md"
|
|
40
41
|
],
|
|
41
42
|
"repository": {
|
|
42
43
|
"type": "git",
|
|
@@ -45,7 +46,7 @@
|
|
|
45
46
|
"description": "Shared conversation memory for coding agents",
|
|
46
47
|
"publishConfig": {
|
|
47
48
|
"access": "public",
|
|
48
|
-
"tag": "
|
|
49
|
+
"tag": "latest"
|
|
49
50
|
},
|
|
50
51
|
"license": "Apache-2.0"
|
|
51
52
|
}
|