@tinchu0/knitt 0.0.0-stage → 0.1.0-beta.1
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/LICENSE +202 -0
- package/README.md +57 -2
- package/dist/apps/server/src/http-gateway.js +118 -0
- package/dist/apps/server/src/http-main.js +46 -0
- package/dist/apps/server/src/main.js +15 -0
- package/dist/apps/server/src/server.js +143 -0
- package/dist/apps/server/src/web-auth.js +30 -0
- package/dist/apps/server/src/web-picker.js +119 -0
- package/dist/packages/adapters/src/cli.js +111 -0
- package/dist/packages/adapters/src/command.js +96 -0
- package/dist/packages/adapters/src/handoff.js +146 -0
- package/dist/packages/adapters/src/hooks.js +86 -0
- package/dist/packages/adapters/src/launch.js +14 -0
- package/dist/packages/adapters/src/picker.js +40 -0
- package/dist/packages/adapters/src/repository.js +20 -0
- package/dist/packages/adapters/src/scope.js +32 -0
- package/dist/packages/adapters/src/transcript.js +138 -0
- package/dist/packages/contracts/src/capabilities.js +1 -0
- package/dist/packages/contracts/src/events.js +27 -0
- package/dist/packages/installer/src/cli.js +210 -0
- package/dist/packages/installer/src/connections.js +226 -0
- package/dist/packages/installer/src/runtime.js +76 -0
- package/dist/packages/memory/src/store.js +91 -0
- package/dist/scripts/connector-setup.js +77 -0
- package/dist/skills/continue-chat/SKILL.md +13 -0
- package/docs/clients/connector-setup.md +63 -0
- package/docs/clients/npm-installation.md +62 -0
- package/package.json +49 -4
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
import { homedir } from 'node:os';
|
|
2
|
+
import { join, resolve } from 'node:path';
|
|
3
|
+
import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, mkdtempSync, writeFileSync } from 'node:fs';
|
|
4
|
+
import { execFileSync } from 'node:child_process';
|
|
5
|
+
import { randomUUID } from 'node:crypto';
|
|
6
|
+
import { atomicWrite } from './connections.js';
|
|
7
|
+
export const packageName = '@tinchu0/knitt';
|
|
8
|
+
export function defaultHome() {
|
|
9
|
+
if (process.env.SHARED_MEMORY_HOME)
|
|
10
|
+
return resolve(process.env.SHARED_MEMORY_HOME);
|
|
11
|
+
if (process.platform === 'darwin')
|
|
12
|
+
return join(homedir(), 'Library/Application Support/SharedAgentMemory');
|
|
13
|
+
if (process.platform === 'win32')
|
|
14
|
+
return join(process.env.LOCALAPPDATA ?? join(homedir(), 'AppData/Local'), 'SharedAgentMemory');
|
|
15
|
+
return join(process.env.XDG_DATA_HOME ?? join(homedir(), '.local/share'), 'shared-agent-memory');
|
|
16
|
+
}
|
|
17
|
+
export function runtimePaths(home) { return { data: join(home, 'data'), versions: join(home, 'versions'), state: join(home, 'installation.json') }; }
|
|
18
|
+
export function readInstallation(home) {
|
|
19
|
+
const path = runtimePaths(home).state;
|
|
20
|
+
if (!existsSync(path))
|
|
21
|
+
return null;
|
|
22
|
+
const value = JSON.parse(readFileSync(path, 'utf8'));
|
|
23
|
+
if (value.schema !== 1 || !value.current?.appRoot || !Array.isArray(value.projects))
|
|
24
|
+
throw new Error('Invalid installation metadata');
|
|
25
|
+
return value;
|
|
26
|
+
}
|
|
27
|
+
export async function withInstallLock(home, work) {
|
|
28
|
+
mkdirSync(home, { recursive: true, mode: 0o700 });
|
|
29
|
+
const lock = join(home, 'install.lock');
|
|
30
|
+
try {
|
|
31
|
+
mkdirSync(lock, { mode: 0o700 });
|
|
32
|
+
}
|
|
33
|
+
catch {
|
|
34
|
+
throw new Error('Another installation is running, or a stale install.lock remains. Check for a running setup process before removing ' + lock);
|
|
35
|
+
}
|
|
36
|
+
try {
|
|
37
|
+
writeFileSync(join(lock, 'owner.json'), JSON.stringify({ pid: process.pid, started: new Date().toISOString() }), { mode: 0o600 });
|
|
38
|
+
return await work();
|
|
39
|
+
}
|
|
40
|
+
finally {
|
|
41
|
+
rmSync(lock, { recursive: true, force: true });
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
export function installRuntime(home, spec) {
|
|
45
|
+
if (process.platform === 'win32')
|
|
46
|
+
throw new Error('Windows installer validation is pending; use WSL for this preview.');
|
|
47
|
+
if (Number(process.versions.node.split('.')[0]) < 24)
|
|
48
|
+
throw new Error('Node.js 24 or newer is required');
|
|
49
|
+
const paths = runtimePaths(home);
|
|
50
|
+
mkdirSync(paths.versions, { recursive: true, mode: 0o700 });
|
|
51
|
+
mkdirSync(paths.data, { recursive: true, mode: 0o700 });
|
|
52
|
+
const staging = mkdtempSync(join(paths.versions, '.staging-'));
|
|
53
|
+
try {
|
|
54
|
+
writeFileSync(join(staging, 'package.json'), JSON.stringify({ name: 'shared-memory-runtime', private: true }), { mode: 0o600 });
|
|
55
|
+
// Arguments are passed directly; no shell interpolation or install lifecycle scripts.
|
|
56
|
+
execFileSync('npm', ['install', '--prefix', staging, '--ignore-scripts', '--omit=dev', '--no-audit', '--no-fund', '--save-exact', '--', spec], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 180_000 });
|
|
57
|
+
const root = join(staging, 'node_modules', packageName);
|
|
58
|
+
const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
|
|
59
|
+
if (pkg.name !== packageName || !/^\d+\.\d+\.\d+(?:-[\w.-]+)?$/.test(pkg.version))
|
|
60
|
+
throw new Error('Unexpected runtime package');
|
|
61
|
+
for (const file of ['apps/server/src/main.js', 'packages/installer/src/cli.js'])
|
|
62
|
+
if (!existsSync(join(root, 'dist', file)))
|
|
63
|
+
throw new Error('Incomplete runtime: ' + file);
|
|
64
|
+
execFileSync(process.execPath, [join(root, 'dist/packages/installer/src/cli.js'), '--version'], { encoding: 'utf8', timeout: 10_000 });
|
|
65
|
+
const destination = join(paths.versions, pkg.version + '-' + randomUUID());
|
|
66
|
+
renameSync(staging, destination);
|
|
67
|
+
return { version: pkg.version, node: process.execPath, appRoot: join(destination, 'node_modules', packageName, 'dist') };
|
|
68
|
+
}
|
|
69
|
+
finally {
|
|
70
|
+
rmSync(staging, { recursive: true, force: true });
|
|
71
|
+
}
|
|
72
|
+
}
|
|
73
|
+
export function activateRuntime(home, current, projects) {
|
|
74
|
+
const previous = readInstallation(home);
|
|
75
|
+
atomicWrite(runtimePaths(home).state, JSON.stringify({ schema: 1, current, previous: previous?.current, projects }, null, 2) + '\n');
|
|
76
|
+
}
|
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
import { DatabaseSync } from "node:sqlite";
|
|
2
|
+
import { eventSchema, scopeSchema, searchSchema } from "../../contracts/src/events.js";
|
|
3
|
+
export class MemoryStore {
|
|
4
|
+
db;
|
|
5
|
+
constructor(path) {
|
|
6
|
+
this.db = new DatabaseSync(path);
|
|
7
|
+
this.db.exec(`
|
|
8
|
+
PRAGMA journal_mode=WAL;
|
|
9
|
+
PRAGMA busy_timeout=5000;
|
|
10
|
+
CREATE TABLE IF NOT EXISTS events (
|
|
11
|
+
seq INTEGER PRIMARY KEY AUTOINCREMENT,
|
|
12
|
+
repo TEXT NOT NULL, id TEXT NOT NULL, feature TEXT NOT NULL,
|
|
13
|
+
branch TEXT, payload TEXT NOT NULL, received TEXT NOT NULL,
|
|
14
|
+
UNIQUE(repo, id)
|
|
15
|
+
);
|
|
16
|
+
CREATE INDEX IF NOT EXISTS events_scope ON events(repo, feature, seq);
|
|
17
|
+
CREATE TABLE IF NOT EXISTS chat_sessions (
|
|
18
|
+
repo TEXT NOT NULL, session TEXT NOT NULL, owner TEXT NOT NULL,
|
|
19
|
+
PRIMARY KEY(repo, session)
|
|
20
|
+
);
|
|
21
|
+
CREATE TABLE IF NOT EXISTS session_selections (
|
|
22
|
+
repo TEXT NOT NULL, session TEXT NOT NULL, feature TEXT NOT NULL, title TEXT NOT NULL,
|
|
23
|
+
PRIMARY KEY(repo, session)
|
|
24
|
+
);
|
|
25
|
+
`);
|
|
26
|
+
}
|
|
27
|
+
save(input) {
|
|
28
|
+
const event = eventSchema.parse(input);
|
|
29
|
+
const payload = JSON.stringify(event);
|
|
30
|
+
const received = new Date().toISOString();
|
|
31
|
+
this.db.prepare("INSERT INTO events(repo,id,feature,branch,payload,received) VALUES(?,?,?,?,?,?) ON CONFLICT(repo,id) DO NOTHING")
|
|
32
|
+
.run(event.repoId, event.eventId, event.featureId, event.branch ?? null, payload, received);
|
|
33
|
+
const row = this.db.prepare("SELECT payload,received FROM events WHERE repo=? AND id=?").get(event.repoId, event.eventId);
|
|
34
|
+
if (row.payload !== payload)
|
|
35
|
+
throw new Error("Event ID conflict");
|
|
36
|
+
return { ...event, receivedAt: String(row.received) };
|
|
37
|
+
}
|
|
38
|
+
context(input) {
|
|
39
|
+
const scope = scopeSchema.parse(input);
|
|
40
|
+
const where = "repo=? AND feature=?" + (scope.branch ? " AND branch=?" : "");
|
|
41
|
+
const params = scope.branch ? [scope.repoId, scope.featureId, scope.branch] : [scope.repoId, scope.featureId];
|
|
42
|
+
const count = this.db.prepare("SELECT COUNT(*) AS total FROM events WHERE " + where).get(...params);
|
|
43
|
+
const rows = this.db.prepare("SELECT payload,received FROM events WHERE " + where + " ORDER BY seq DESC LIMIT 1000").all(...params);
|
|
44
|
+
const events = [];
|
|
45
|
+
let used = 2;
|
|
46
|
+
for (const row of rows) {
|
|
47
|
+
const event = { ...JSON.parse(String(row.payload)), receivedAt: String(row.received) };
|
|
48
|
+
const size = JSON.stringify(event).length + (events.length ? 1 : 0);
|
|
49
|
+
if (used + size > scope.maxChars)
|
|
50
|
+
break;
|
|
51
|
+
used += size;
|
|
52
|
+
events.push(event);
|
|
53
|
+
}
|
|
54
|
+
return { events, total: Number(count.total), truncated: events.length < Number(count.total), order: "newest_first", contentTrust: "untrusted_reference" };
|
|
55
|
+
}
|
|
56
|
+
evidence(repoId, eventId) {
|
|
57
|
+
const row = this.db.prepare("SELECT payload,received FROM events WHERE repo=? AND id=?").get(repoId, eventId);
|
|
58
|
+
return row ? { ...JSON.parse(String(row.payload)), receivedAt: String(row.received) } : null;
|
|
59
|
+
}
|
|
60
|
+
search(input) {
|
|
61
|
+
const scope = searchSchema.parse(input);
|
|
62
|
+
const rows = this.db.prepare("SELECT seq,payload,received FROM events WHERE repo=? AND feature=? AND seq < ? " +
|
|
63
|
+
"AND instr(lower(json_extract(payload,'$.content')),lower(?)) > 0 ORDER BY seq DESC LIMIT ?").all(scope.repoId, scope.featureId, scope.before ?? Number.MAX_SAFE_INTEGER, scope.query, scope.limit + 1);
|
|
64
|
+
const selected = rows.slice(0, scope.limit);
|
|
65
|
+
const matches = selected.map(row => {
|
|
66
|
+
const event = JSON.parse(String(row.payload));
|
|
67
|
+
const { content, ...metadata } = event;
|
|
68
|
+
const match = content.toLowerCase().indexOf(scope.query.toLowerCase());
|
|
69
|
+
const start = Math.max(0, match - 100);
|
|
70
|
+
return { ...metadata, receivedAt: String(row.received), excerpt: content.slice(start, start + 1000) };
|
|
71
|
+
});
|
|
72
|
+
return { matches, nextCursor: rows.length > scope.limit ? Number(selected[selected.length - 1].seq) : null };
|
|
73
|
+
}
|
|
74
|
+
createChatSession(repoId, sessionId, owner) {
|
|
75
|
+
this.db.prepare("INSERT INTO chat_sessions VALUES(?,?,?)").run(repoId, sessionId, owner);
|
|
76
|
+
}
|
|
77
|
+
ownsChatSession(repoId, sessionId, owner) {
|
|
78
|
+
return !!this.db.prepare("SELECT 1 FROM chat_sessions WHERE repo=? AND session=? AND owner=?").get(repoId, sessionId, owner);
|
|
79
|
+
}
|
|
80
|
+
selectSession(repoId, sessionId, featureId, title) {
|
|
81
|
+
if (!repoId || !sessionId || !featureId)
|
|
82
|
+
throw new Error("Repository, session and selected feature are required");
|
|
83
|
+
this.db.prepare("INSERT INTO session_selections VALUES(?,?,?,?) ON CONFLICT(repo,session) DO UPDATE SET feature=excluded.feature,title=excluded.title")
|
|
84
|
+
.run(repoId, sessionId, featureId, title);
|
|
85
|
+
}
|
|
86
|
+
sessionSelection(repoId, sessionId) {
|
|
87
|
+
const row = this.db.prepare("SELECT feature,title FROM session_selections WHERE repo=? AND session=?").get(repoId, sessionId);
|
|
88
|
+
return row ? { featureId: String(row.feature), title: String(row.title) } : null;
|
|
89
|
+
}
|
|
90
|
+
close() { this.db.close(); }
|
|
91
|
+
}
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
import { parseArgs } from "node:util";
|
|
2
|
+
import { resolve, join } from "node:path";
|
|
3
|
+
import { fileURLToPath } from "node:url";
|
|
4
|
+
import { mkdirSync, writeFileSync } from "node:fs";
|
|
5
|
+
import { planConnection, applyConnectionPlan } from "../packages/installer/src/connections.js";
|
|
6
|
+
import { createHash } from "node:crypto";
|
|
7
|
+
import { resolveRepository } from "../packages/adapters/src/repository.js";
|
|
8
|
+
function secureUrl(value, name) {
|
|
9
|
+
const url = new URL(value);
|
|
10
|
+
if (url.protocol !== "https:" || url.username || url.password || url.search || url.hash)
|
|
11
|
+
throw new Error(name + " must be a clean HTTPS URL");
|
|
12
|
+
return url;
|
|
13
|
+
}
|
|
14
|
+
try {
|
|
15
|
+
const { values } = parseArgs({ options: {
|
|
16
|
+
client: { type: "string" }, workspace: { type: "string", default: process.cwd() },
|
|
17
|
+
"public-url": { type: "string" }, issuer: { type: "string" },
|
|
18
|
+
subject: { type: "string", multiple: true }, preview: { type: "boolean", default: false },
|
|
19
|
+
} });
|
|
20
|
+
const client = values.client;
|
|
21
|
+
if (!client || !["claude-code", "claude-desktop", "chatgpt", "claude-web"].includes(client)) {
|
|
22
|
+
throw new Error("Choose --client claude-code, claude-desktop, chatgpt or claude-web");
|
|
23
|
+
}
|
|
24
|
+
const app = resolve(fileURLToPath(new URL("../", import.meta.url)));
|
|
25
|
+
const { workspace, repoId } = resolveRepository(resolve(values.workspace));
|
|
26
|
+
if (client === "claude-code" || client === "claude-desktop") {
|
|
27
|
+
const plan = planConnection({ workspace, appRoot: app, database: process.env.MEMORY_DB ?? join(app, ".memory/events.sqlite"), repoId, clients: [client] });
|
|
28
|
+
for (const path of Object.keys(plan.changes))
|
|
29
|
+
console.log("merge " + join(workspace, path));
|
|
30
|
+
if (!values.preview)
|
|
31
|
+
applyConnectionPlan(plan);
|
|
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."
|
|
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
|
+
}
|
|
36
|
+
else {
|
|
37
|
+
const publicUrl = values["public-url"] ? secureUrl(values["public-url"], "Public URL") : null;
|
|
38
|
+
if (publicUrl) {
|
|
39
|
+
if (!["/", "/mcp"].includes(publicUrl.pathname))
|
|
40
|
+
throw new Error("Use a dedicated HTTPS host or its /mcp endpoint");
|
|
41
|
+
publicUrl.pathname = "/mcp";
|
|
42
|
+
}
|
|
43
|
+
if (values.issuer)
|
|
44
|
+
secureUrl(values.issuer, "OAuth issuer");
|
|
45
|
+
const missing = [
|
|
46
|
+
...(!publicUrl ? ["public HTTPS URL"] : []),
|
|
47
|
+
...(!values.issuer ? ["OAuth issuer"] : []),
|
|
48
|
+
...(!values.subject?.length ? ["allowed OAuth subject(s)"] : []),
|
|
49
|
+
];
|
|
50
|
+
const profile = {
|
|
51
|
+
client, status: missing.length ? "configuration_required" : "ready_to_serve", missing,
|
|
52
|
+
server: {
|
|
53
|
+
repoId, workspace, database: process.env.MEMORY_DB ?? join(app, ".memory/events.sqlite"),
|
|
54
|
+
publicUrl: publicUrl?.href ?? null, issuer: values.issuer ?? null, allowedSubjects: values.subject ?? [],
|
|
55
|
+
},
|
|
56
|
+
connection: {
|
|
57
|
+
name: "Shared Memory — " + workspace.split("/").at(-1),
|
|
58
|
+
mcpUrl: publicUrl?.href ?? null, authentication: "OAuth 2.1",
|
|
59
|
+
setup: client === "chatgpt" ? "Add a custom MCP connector in ChatGPT's developer/connector settings."
|
|
60
|
+
: "Add a custom remote connector in Claude's connector settings.",
|
|
61
|
+
},
|
|
62
|
+
capture: "Tool-based saves. Ordinary chat clients do not expose coding-session capture hooks.",
|
|
63
|
+
};
|
|
64
|
+
const path = join(app, ".memory/connectors", client + "-" + createHash("sha256").update(repoId).digest("hex").slice(0, 8) + ".json");
|
|
65
|
+
if (!values.preview) {
|
|
66
|
+
mkdirSync(join(app, ".memory/connectors"), { recursive: true, mode: 0o700 });
|
|
67
|
+
writeFileSync(path, JSON.stringify(profile, null, 2) + "\n", { mode: 0o600 });
|
|
68
|
+
}
|
|
69
|
+
console.log(JSON.stringify({ path, ...profile }, null, 2));
|
|
70
|
+
if (!missing.length)
|
|
71
|
+
console.log("Start the authenticated gateway with: npm run serve:http -- --profile " + JSON.stringify(path));
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
catch (error) {
|
|
75
|
+
console.error(error instanceof Error ? error.message : String(error));
|
|
76
|
+
process.exitCode = 1;
|
|
77
|
+
}
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: continue-chat
|
|
3
|
+
description: Open the shared-memory chat picker and load the conversation the user selects.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
<!-- shared-agent-memory -->
|
|
7
|
+
# Continue a chat
|
|
8
|
+
|
|
9
|
+
Use the native session ID and repository from the memory startup hook. Immediately call shared-memory's choose_conversation with that sessionId. Let the user select a chat in the form. Do not select a chat on their behalf.
|
|
10
|
+
|
|
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
|
+
|
|
13
|
+
If the startup session ID or server is unavailable, report that the project memory connection needs to be loaded. Never invent a session ID. For clients without MCP forms, direct the user to the product's local picker.
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
# Connector setup
|
|
2
|
+
|
|
3
|
+
Run commands from the memory product checkout with Node 24+ and dependencies installed (`npm ci`). Replace `/path/to/repository` with the project you want to continue. These commands configure that repository, not the memory product itself.
|
|
4
|
+
|
|
5
|
+
## Claude Code
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npm run connect -- --client claude-code --workspace /path/to/repository
|
|
9
|
+
```
|
|
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.
|
|
12
|
+
|
|
13
|
+
## Claude Desktop local MCP
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
npm run connect -- --client claude-desktop --workspace /path/to/repository
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
The installer writes a configuration fragment to the project's `.memory/connectors/claude-desktop.json`. Merge its `mcpServers` entry into Claude Desktop's local MCP configuration on the same machine, then restart Desktop. Absolute executable, application and database paths must exist on that machine. This command prepares the fragment; it does not modify or verify the Desktop application.
|
|
20
|
+
|
|
21
|
+
The server instructs the agent to call `start_session`, then `choose_conversation`. Choose explicitly in the form when supported. The local fallback is the terminal handoff picker. Local Desktop chat uses tool-based saves; coding hooks do not capture ordinary Desktop chats.
|
|
22
|
+
|
|
23
|
+
## ChatGPT and Claude web
|
|
24
|
+
|
|
25
|
+
Generate a private setup profile:
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
npm run connect -- --client chatgpt --workspace /path/to/repository
|
|
29
|
+
npm run connect -- --client claude-web --workspace /path/to/repository
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
Without deployment values, these profiles report `configuration_required`. They do not establish a live connection. Complete a profile by rerunning with your actual values:
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
npm run connect -- --client chatgpt --workspace /path/to/repository \
|
|
36
|
+
--public-url https://memory.example.com/mcp \
|
|
37
|
+
--issuer https://identity.example.com \
|
|
38
|
+
--subject YOUR_OAUTH_USER_SUBJECT
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
Repeat `--subject` to allow teammates. Use `--preview` to inspect setup without writing files. Profiles are stored under the product's ignored `.memory/connectors/` directory. The generated output supplies the exact command to start the server:
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
npm run serve:http -- --profile /absolute/path/to/generated-profile.json
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
The gateway listens on `127.0.0.1:8787`. Forward the entire dedicated HTTPS hostname through a reverse proxy or tunnel, including `/mcp`, discovery and picker routes. This release uses local SQLite: keep the database on durable storage beside the running service. It is not a stateless Cloud Run deployment recipe.
|
|
48
|
+
|
|
49
|
+
Configure an external OAuth/OIDC provider with authorization-code flow and PKCE S256. Its discovery document must identify the exact configured issuer and an HTTPS JWKS endpoint. Access tokens must be signed JWTs (RS256 or ES256), with an expiry, an allowlisted subject, audience equal to the public `/mcp` URL, and `memory:read` scope. Add `memory:write` for checkpoint saves. The provider must support the target client's registration or preconfigured client credentials and redirect URLs; this service does not implement an authorization server or dynamic client registration itself. Opaque access tokens are unsupported.
|
|
50
|
+
|
|
51
|
+
Add the public MCP URL as a custom remote connector in the chosen client and complete OAuth there. Provider setup and a live client login are required in addition to running this gateway. One gateway profile binds one repository; allowed users share selected feature evidence in that repository.
|
|
52
|
+
|
|
53
|
+
## Selecting and continuing
|
|
54
|
+
|
|
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
|
+
|
|
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.
|
|
58
|
+
|
|
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
|
+
|
|
61
|
+
## Verification status
|
|
62
|
+
|
|
63
|
+
The automated suite exercises real MCP HTTP connections, OAuth validation, explicit selection, single-use picker links, independent chat sessions, user ownership and write scopes. Local Claude Code configuration is installed and recognized by the CLI, pending login and MCP approval. Desktop configuration is generated but the application is untested. ChatGPT and Claude web are not live-connected: public HTTPS and OAuth configuration are still required. Browser picker endpoints are tested; visual rendering has not been independently verified.
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
# npm installation and runtime lifecycle
|
|
2
|
+
|
|
3
|
+
## Try the unpublished release candidate
|
|
4
|
+
|
|
5
|
+
Build and pack from the repository:
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npm ci
|
|
9
|
+
npm run check
|
|
10
|
+
npm run build
|
|
11
|
+
npm pack
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
Then use the tarball (absolute paths work from any directory):
|
|
15
|
+
|
|
16
|
+
```bash
|
|
17
|
+
npx --yes --package ./tinchu0-knitt-0.1.0-beta.1.tgz knitt setup \
|
|
18
|
+
--workspace /path/to/project --client codex --client claude-code \
|
|
19
|
+
--package /absolute/path/to/tinchu0-knitt-0.1.0-beta.1.tgz
|
|
20
|
+
```
|
|
21
|
+
|
|
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
|
+
|
|
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
|
+
|
|
26
|
+
## Durable installation
|
|
27
|
+
|
|
28
|
+
The default installation directory is:
|
|
29
|
+
|
|
30
|
+
- Linux: `$XDG_DATA_HOME/shared-agent-memory` or `~/.local/share/shared-agent-memory`.
|
|
31
|
+
- macOS: `~/Library/Application Support/SharedAgentMemory` (platform validation pending).
|
|
32
|
+
|
|
33
|
+
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
|
+
|
|
35
|
+
The setup process uses npm to install production dependencies in staging with dependency lifecycle scripts disabled. It verifies the packaged executable before rebinding connectors. The temporary npx cache can then be removed without breaking installed connections. Installation metadata uses an exclusive lock; after a crash, inspect the PID in `install.lock/owner.json` before removing a stale lock.
|
|
36
|
+
|
|
37
|
+
The project-local `.memory/npm-connection.json` records original and generated settings. Keep it until uninstall. Do not commit this private file. Existing Git excludes are extended for local generated settings. Existing Python-installed connections are considered unmanaged by the new CLI: they are not silently adopted or overwritten. Use a fresh project for the release candidate, or restore the legacy connector backups before migrating deliberately.
|
|
38
|
+
|
|
39
|
+
## Commands
|
|
40
|
+
|
|
41
|
+
Run commands through the tarball CLI above (or the eventual published package):
|
|
42
|
+
|
|
43
|
+
```text
|
|
44
|
+
knitt setup --workspace PATH --client codex --preview
|
|
45
|
+
knitt doctor
|
|
46
|
+
knitt update --yes
|
|
47
|
+
knitt rollback --yes
|
|
48
|
+
knitt uninstall --workspace PATH --yes
|
|
49
|
+
knitt serve
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
Use the same `--home` for every lifecycle command if you customized it. `doctor` checks local installation/configuration, not account login or a live model handoff. Changed settings are reported for review.
|
|
53
|
+
|
|
54
|
+
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.
|
|
55
|
+
|
|
56
|
+
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.
|
|
57
|
+
|
|
58
|
+
## Release gates
|
|
59
|
+
|
|
60
|
+
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 deliberately fails rather than writing POSIX hook commands. Linux tarball checks are the current local verification target; macOS/Windows live client behavior remains unverified.
|
|
61
|
+
|
|
62
|
+
ChatGPT, Claude web and teammate machines require a separately reachable authenticated service. Packaging a CLI does not supply hosting, authentication accounts or background synchronization.
|
package/package.json
CHANGED
|
@@ -1,6 +1,51 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@tinchu0/knitt",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.1.0-beta.1",
|
|
4
|
+
"type": "module",
|
|
5
|
+
"engines": {
|
|
6
|
+
"node": ">=24"
|
|
7
|
+
},
|
|
8
|
+
"scripts": {
|
|
9
|
+
"start": "node apps/server/src/main.ts",
|
|
10
|
+
"test": "node --test tests/*.test.ts",
|
|
11
|
+
"check": "tsc --noEmit",
|
|
12
|
+
"memory": "node packages/adapters/src/command.ts",
|
|
13
|
+
"connect": "node scripts/connector-setup.ts",
|
|
14
|
+
"serve:http": "node apps/server/src/http-main.ts",
|
|
15
|
+
"build": "node scripts/build.ts",
|
|
16
|
+
"test:package": "npm run build && node scripts/package-smoke.ts",
|
|
17
|
+
"prepack": "npm run check && npm run build"
|
|
18
|
+
},
|
|
19
|
+
"dependencies": {
|
|
20
|
+
"@modelcontextprotocol/sdk": "^1.32.2",
|
|
21
|
+
"express": "^5.3.0",
|
|
22
|
+
"jose": "^6.2.17",
|
|
23
|
+
"smol-toml": "^1.9.1",
|
|
24
|
+
"zod": "^4.6.7"
|
|
25
|
+
},
|
|
26
|
+
"devDependencies": {
|
|
27
|
+
"@types/express": "^5.0.6",
|
|
28
|
+
"@types/node": "^26.6.6",
|
|
29
|
+
"typescript": "^7.0.2"
|
|
30
|
+
},
|
|
31
|
+
"bin": {
|
|
32
|
+
"knitt": "dist/packages/installer/src/cli.js"
|
|
33
|
+
},
|
|
34
|
+
"files": [
|
|
35
|
+
"dist/",
|
|
36
|
+
"README.md",
|
|
37
|
+
"docs/clients/connector-setup.md",
|
|
38
|
+
"docs/clients/npm-installation.md",
|
|
39
|
+
"LICENSE"
|
|
40
|
+
],
|
|
41
|
+
"repository": {
|
|
42
|
+
"type": "git",
|
|
43
|
+
"url": "git+https://github.com/darthnihilus01/knitt.git"
|
|
44
|
+
},
|
|
45
|
+
"description": "Shared conversation memory for coding agents",
|
|
46
|
+
"publishConfig": {
|
|
47
|
+
"access": "public",
|
|
48
|
+
"tag": "next"
|
|
49
|
+
},
|
|
50
|
+
"license": "Apache-2.0"
|
|
51
|
+
}
|