suture-mcp 0.1.1 → 0.2.0-rc.0

package/README.md

@@ -1,9 +1,9 @@
-# suture-mcp (Beta)
+# suture-mcp (0.2 Release Candidate)
 
 Persistent structured memory for AI agents. Suture is an MCP-native, zero-infra memory substrate that stores curated local context in SQLite, then exposes it through model-agnostic tools and CLI hooks.
 
 > [!IMPORTANT]
-> **Beta Status:** Suture is currently in local-first beta. Expect breaking changes to the database schema and tool definitions. **Do not use for highly sensitive production credentials.**
+> **Release Candidate Status:** Suture is preparing the `v0.2.0` stable local-core release. The current candidate keeps the beta privacy boundary: local SQLite by default, no hosted sync by default, and no raw repository upload. **Do not use for highly sensitive production credentials.**
 
 ## Quickstart
 
@@ -15,45 +15,86 @@ npx suture-mcp@beta setup
 
 The setup flow checks the local runtime, previews the state directory and MCP config, shows the safe project index plan, lets you toggle durable project facts with the keyboard, runs indexing, then ends on a value dashboard with estimated token savings and curation activity.
 
-For agents, CI, and scripted installs:
+### Try Suture once with `npx`
+
+Use this path when you want to test Suture without installing a persistent CLI:
 
 ```bash
 npx suture-mcp@beta setup --yes --project /path/to/project --dir /path/to/suture-data
-suture-mcp index /path/to/project --apply-safe --json
-suture-mcp stats --json
+npx suture-mcp@beta stats --dir /path/to/suture-data
 ```
 
-Until the npm beta tag is published, use the GitHub fallback with an explicit package command:
+`npx` downloads and runs the package for that command. It does not guarantee a lasting `suture` command on your PATH after the command exits.
 
-```bash
-npm exec --yes --package github:AlejandroZmtZ/suture-mcp -- suture-mcp setup
-```
+### Install the CLI for agents
 
-If npm reports `spawn sh ENOENT` on native dependency install, set the lifecycle script shell explicitly and retry:
+Use this path when MCP agents need to launch Suture repeatedly:
 
 ```bash
-npm config set script-shell /bin/sh
-npm exec --yes --package github:AlejandroZmtZ/suture-mcp -- suture-mcp doctor
+npm install -g suture-mcp@beta
+suture setup --yes --project /path/to/project --dir /path/to/suture-data
+suture configure-agents --project /path/to/project --dir /path/to/suture-data --agents codex,gemini,claude,cursor,vscode,continue
+suture stats --dir /path/to/suture-data
 ```
 
-The printed MCP config is ready to paste into your agent:
+Installed CLI is recommended for real agent use because generated MCP configs can rely on:
 
 ```json
 {
   "mcpServers": {
     "suture": {
-      "command": "suture-mcp",
+      "command": "suture",
       "args": ["serve", "--dir", "/path/to/suture-data"]
     }
   }
 }
 ```
 
+If you intentionally want an agent to launch through `npx`, use:
+
+```json
+{
+  "mcpServers": {
+    "suture": {
+      "command": "npx",
+      "args": ["-y", "suture-mcp@beta", "serve", "--dir", "/path/to/suture-data"]
+    }
+  }
+}
+```
+
+That works, but startup depends on npm/cache behavior and can be slower than an installed CLI.
+
+Until the npm beta tag is published, use the GitHub fallback with an explicit package command:
+
+```bash
+npm exec --yes --package github:AlejandroZmtZ/suture-mcp -- suture setup
+```
+
+If npm reports `spawn sh ENOENT` on native dependency install, set the lifecycle script shell explicitly and retry:
+
+```bash
+npm config set script-shell /bin/sh
+npm exec --yes --package github:AlejandroZmtZ/suture-mcp -- suture doctor
+```
+
+Or let Suture write supported local agent configs for you:
+
+```bash
+suture configure-agents --project /path/to/project --dir /path/to/suture-data --agents codex,gemini,claude,cursor,vscode,continue
+```
+
+This creates timestamped `.bak-suture-*` backups before editing config files. For a preview without writing:
+
+```bash
+suture configure-agents --project /path/to/project --dir /path/to/suture-data --agents all --dry-run
+```
+
 Once connected:
 
 - **Remember:** Ask your agent to "remember this decision: we are using SQLite for persistence."
 - **Search:** Ask "what did we decide about persistence?"
-- **Stats:** Run `suture-mcp stats` to see estimated cached tokens, avoided rereads, indexed files, curation actions, and cost savings.
+- **Stats:** Run `suture stats` to see estimated cached tokens, avoided rereads, indexed files, curation actions, and cost savings.
 
 ## Beta Install Validation
 
@@ -68,15 +109,32 @@ npx suture-mcp@beta stats --dir /path/to/shared-suture-state
 
 The second setup should report an existing substrate, apply zero duplicate facts, skip unchanged files, and show avoided reread tokens in the stats dashboard. That is the expected second-agent path for Claude, Codex, Cursor, or any other MCP-capable client using the same state directory.
 
-## Beta Safety & Limitations
+### Codex MCP Validation
 
-Suture is in **local-first beta**. It is designed with a defense-in-depth security posture, but please note these limitations:
+For a safe Codex test, validate Suture with a disposable state directory and an isolated Codex config first:
+
+```bash
+node dist/cli.js setup --yes --project /home/alex/suture-mcp --dir /tmp/suture-codex-qa --json
+node dist/cli.js configure-agents --project /home/alex/suture-mcp --dir /tmp/suture-codex-qa --agents codex --dry-run --json
+
+rm -rf /tmp/codex-suture-qa-home
+mkdir -p /tmp/codex-suture-qa-home
+CODEX_HOME=/tmp/codex-suture-qa-home codex mcp add suture -- suture-mcp serve --dir /tmp/suture-codex-qa
+CODEX_HOME=/tmp/codex-suture-qa-home codex mcp list
+CODEX_HOME=/tmp/codex-suture-qa-home codex mcp get suture
+```
+
+This route does not modify your real `~/.codex/config.toml`. After you intentionally add Suture to your real Codex config, start a new Codex session so the MCP server list is loaded fresh.
+
+## Release Candidate Safety & Limitations
+
+Suture is in **local-first release-candidate validation**. It is designed with a defense-in-depth security posture, but please note these limitations:
 
 - **Secret Detection:** Suture uses a regex-based scanner to block obvious API keys (OpenAI, AWS, etc.) and `.env` secrets. This is **best-effort** and not a replacement for a dedicated DLP solution.
-- **Privacy:** Data stays on your machine in a local SQLite database. There is no cloud sync or telemetry in the beta.
+- **Privacy:** Data stays on your machine in a local SQLite database. There is no cloud sync or telemetry in the local-core release.
 - **Disabled Tools:** The `import` tool is explicitly disabled in beta to prevent unsafe database restores.
 - **Native Dependencies:** Uses `better-sqlite3` and `tree-sitter`. Installation may require a working Node.js build environment (GXX/Xcode) on some systems.
-- **Breaking Changes:** Schema migrations are supported, but we recommend regular `transfer` exports of critical memory during beta.
+- **Breaking Changes:** Schema migrations are supported, but we recommend regular `transfer` exports of critical memory until `v0.2.0` exits release-candidate validation.
 
 ## Current Capabilities
 
@@ -93,7 +151,7 @@ Suture is in **local-first beta**. It is designed with a defense-in-depth securi
 
 ```bash
 npm install -g suture-mcp
-suture-mcp setup --project /path/to/project --dir /path/to/state
+suture setup --project /path/to/project --dir /path/to/state
 ```
 
 For local development:
@@ -109,7 +167,7 @@ npm test
 Start the server over stdio:
 
 ```bash
-suture-mcp serve --dir /path/to/state
+suture serve --dir /path/to/state
 ```
 
 Example MCP client configuration (Note: Use absolute paths; many clients do not expand `~`):
@@ -118,7 +176,7 @@ Example MCP client configuration (Note: Use absolute paths; many clients do not
 {
   "mcpServers": {
     "suture": {
-      "command": "suture-mcp",
+      "command": "suture",
       "args": ["serve", "--dir", "/home/user/.suture"]
     }
   }
@@ -128,18 +186,22 @@ Example MCP client configuration (Note: Use absolute paths; many clients do not
 ## CLI
 
 ```bash
-suture-mcp setup [--project <path>] [--dir <state>] [--yes] [--json]
-suture-mcp init [--dir <path>]
-suture-mcp serve [--dir <path>]
-suture-mcp viz [--dir <state>] [--port <port>]
-suture-mcp doctor [--dir <state>] [--json]
-suture-mcp index <project> [--dir <state>] [--apply-safe] [--json]
-suture-mcp hook session-start --project <path> --session <id> [--client <name>] [--format text|json|claude-json]
-suture-mcp hook pre-compact --project <path> --session <id> [--client <name>] [--json]
-suture-mcp hook post-compact --project <path> --session <id> [--client <name>] [--summary <text>|--summary-file <path>] [--json]
-suture-mcp hook status --project <path> --session <id> [--client <name>] [--json]
-suture-mcp stats [--dir <state>] [--json] [--model-profile conservative|standard|premium]
-suture-mcp recall [--dir <state>]
+suture setup [--project <path>] [--dir <state>] [--yes] [--json]
+suture setup [--project <path>] [--dir <state>] [--configure-agents] [--agents codex,gemini,claude,cursor,vscode,windsurf,cline,continue,vibe|all]
+suture init [--dir <path>]
+suture configure-agents [--project <path>] [--dir <state>] [--agents codex,gemini,claude,cursor,vscode,windsurf,cline,continue,vibe|all] [--dry-run] [--json]
+suture serve [--dir <path>]
+suture viz [--dir <state>] [--port <port>]
+suture export --out <path> [--encrypted] [--json] [--passphrase-env <name>]
+suture state encryption status [--dir <state>] [--json]
+suture doctor [--dir <state>] [--json]
+suture index <project> [--dir <state>] [--apply-safe] [--json]
+suture hook session-start --project <path> --session <id> [--client <name>] [--format text|json|claude-json]
+suture hook pre-compact --project <path> --session <id> [--client <name>] [--json]
+suture hook post-compact --project <path> --session <id> [--client <name>] [--summary <text>|--summary-file <path>] [--json]
+suture hook status --project <path> --session <id> [--client <name>] [--json]
+suture stats [--dir <state>] [--json] [--model-profile conservative|standard|premium]
+suture recall [--dir <state>]
 ```
 
 `index` previews by default. Persistence requires `--apply-safe`.
@@ -153,10 +215,97 @@ Beta indexing is deliberately conservative: manifest/config/script/test/code-sym
 Run the local dashboard against a Suture state directory:
 
 ```bash
-suture-mcp viz --dir /path/to/suture-data
+suture viz --dir /path/to/suture-data
 ```
 
-The viz server binds only to `127.0.0.1`. It prints a one-time local URL containing a random token, and all `/api/*` routes require that token. The dashboard uses local assets only, so it does not load graph code from a CDN.
+The viz server binds only to `127.0.0.1`. It prints a one-time local session URL, sends the token to APIs with `x-suture-viz-token`, and all `/api/*` routes require that token. This protects browser/API access, not a compromised OS user. The dashboard uses local assets only, so it does not load graph code from a CDN.
+
+### Encrypted Exports
+
+Plain SQLite remains the beta default. For a portable protected backup, export active memory to an encrypted artifact:
+
+```bash
+suture export --encrypted --out /tmp/suture-export.enc.json
+```
+
+For CI or scripted flows, provide the passphrase through an environment variable:
+
+```bash
+SUTURE_EXPORT_PASSPHRASE='change-me' suture export --encrypted --out /tmp/suture-export.enc.json --json
+```
+
+Check the current live-state encryption posture:
+
+```bash
+suture state encryption status --dir /path/to/suture-data
+```
+
+Live SQLite encryption and encrypted import are not enabled in this beta pass.
+
+### Agent Auto-Configuration
+
+`configure-agents` adds the Suture MCP server to supported local agent config files. It is best for installed CLI usage where the agent can repeatedly launch `suture serve` or `suture-mcp serve` from PATH. For one-off `npx` testing, keep the MCP command as `npx` with args `["-y", "suture-mcp@beta", "serve", "--dir", "..."]` instead of writing an installed-command config.
+
+- Codex: `~/.codex/config.toml`, using `[mcp_servers.suture]`.
+- Gemini CLI: `<project>/.gemini/settings.json`, using `mcpServers.suture`.
+- Claude Code: `<project>/.mcp.json`, using `mcpServers.suture`.
+- Cursor: `<project>/.cursor/mcp.json`, using `mcpServers.suture`.
+- VS Code / Copilot: `<project>/.vscode/mcp.json`, using `servers.suture`.
+- Windsurf: `~/.codeium/windsurf/mcp_config.json`, using `mcpServers.suture`.
+- Cline: `~/.cline/data/settings/cline_mcp_settings.json`, using `mcpServers.suture`.
+- Continue: `<project>/.continue/mcpServers/suture-mcp.yaml`, using a standalone `mcpServers` block.
+- Mistral Vibe: `~/.vibe/config.toml`, using `[[mcp_servers]]` with `transport = "stdio"`.
+
+`all` configures every supported host. Use `--dry-run` first if you want to inspect every file Suture would touch.
+For real writes, pass an explicit `--agents` list or `--agents all`; omitting the flag is limited to dry-run previews so user-home configs are not changed accidentally.
+
+Example:
+
+```bash
+suture configure-agents \
+  --project /home/alex/fronterre-assessment-platform \
+  --dir /home/alex/.suture/fronterre-assessment-platform \
+  --agents codex,gemini,claude,cursor,vscode,continue
+```
+
+Native installation also writes a project-local instruction pack so the harness knows how to use Suture as a memory substrate immediately after MCP reload:
+
+```bash
+suture configure-agents \
+  --project /home/alex/fronterre-assessment-platform \
+  --dir /home/alex/.suture/fronterre-assessment-platform \
+  --agents codex,gemini,cursor \
+  --native \
+  --dry-run
+
+suture configure-agents \
+  --project /home/alex/fronterre-assessment-platform \
+  --agents codex,gemini,cursor \
+  --verify \
+  --json
+```
+
+Native integration is intentionally conservative:
+
+- MCP launch config is schema-aware and backed up before writes.
+- Instruction files are project-local by default.
+- User-home writes happen only for clients whose MCP config is user-scoped.
+- Agents should reload or start a new session after install.
+- The tool guide is also available at `suture://resources/tool-guide`.
+
+You can also run setup and configure agents in one pass:
+
+```bash
+suture setup \
+  --project /home/alex/fronterre-assessment-platform \
+  --dir /home/alex/.suture/fronterre-assessment-platform \
+  --configure-agents \
+  --agents codex,gemini,claude,cursor,vscode,continue
+```
+
+Restart each agent after changing MCP config. Claude Code may prompt for project-scoped MCP approval the first time it sees `.mcp.json`.
+
+Ollama, llama.cpp, and LM Studio are model runtimes/providers rather than MCP hosts. Use Suture through an MCP-capable harness that can call those models, such as Continue, Cline, Mistral Vibe, Open WebUI, or another MCP client. ChatGPT custom connectors, Le Chat connectors, and Open WebUI's native MCP path generally require a remote Streamable HTTP MCP endpoint, which is separate from Suture's local stdio server.
 
 ## Multi-Agent Sharing
 
@@ -166,7 +315,7 @@ Suture memory is shared by state directory, not by model provider. Configure eve
 {
   "mcpServers": {
     "suture": {
-      "command": "suture-mcp",
+      "command": "suture",
       "args": ["serve", "--dir", "/path/to/shared-suture-state"]
     }
   }
@@ -194,6 +343,25 @@ Recommended integration pattern for a new harness:
 4. Call `curate` periodically or after compaction. Suture also runs event-based curation after `remember`, accepted discovery/indexing changes, and discovery apply.
 5. Keep raw transcripts out of durable memory.
 
+### Sleep-Time Maintenance
+
+Suture uses existing hook workflows to run bounded local maintenance after compaction and status-safe idle checks. The sleep-time cycle records an audit event, plans maintenance, refreshes local retrieval indexes when the runtime has index access, and avoids automatic destructive invalidation unless an explicit maintenance apply is requested.
+
+### Semantic Retrieval
+
+Suture keeps deterministic FTS5 retrieval and adds a local vector reranker over FTS5 candidates. The default vectorizer is offline and provider-free, so search quality improves without sending project memory to an external embedding service. Project-scoped searches pass project identity through FTS and vector reranking before results are returned.
+
+### Maintenance Automation
+
+Manual tools remain available, and the safer automated flow is:
+
+```bash
+suture maintenance plan --project-id <project-id> --allow-invalidation --json
+suture maintenance apply --plan <plan-id> --actions <comma-separated-action-ids> --json
+```
+
+Maintenance plans can propose retain, promote, archive, invalidate, and reindex actions. Only selected action IDs are applied, and invalidation removes search indexes and writes an audit row instead of hard-deleting records.
+
 ## Security Boundaries
 
 Suture is local-first by default. It is designed to avoid storing raw prompt transcripts and to reject obvious secrets before persistence.
@@ -213,22 +381,24 @@ These protections are defense-in-depth, not a replacement for a dedicated secret
 The open-core path is straightforward:
 
 - Free local package: single-user memory, discovery, CLI hooks, and visualization.
-- Paid team layer: encrypted sync, shared project maps, audit logs, policy controls, hosted backups, and admin review.
+- Paid team layer: encrypted metadata sync, reviewed shared project maps, audit logs, policy controls, hosted backups, and admin review.
 - Enterprise layer: SSO, retention controls, compliance exports, private deployment, and model/harness fleet observability.
 
+Team sync is governed by a strict data boundary: memory summaries, provenance, project identity, schema versions, maintenance audit, reviewed project facts, and harness fleet status are eligible for encrypted metadata sync. Raw repository files remain local unless a premium hosted workspace is explicitly approved and acknowledges raw repository upload.
+
 The product moat is not a single model integration. It is trusted, portable, policy-aware memory that follows the work across tools.
 
-## Publishing Beta
+## Publishing Release Candidates
 
-Publish beta builds with an npm dist tag instead of asking users to install from Git:
+Publish release candidates with an npm dist tag instead of asking users to install from Git:
 
 ```bash
 npm --cache /tmp/suture-npm-cache pack --dry-run
 npm whoami
-npm publish --tag beta
+npm publish --tag rc
 ```
 
-Keep the beta promise narrow and excellent: frictionless terminal setup, local-only privacy, safe project indexing, honest estimated savings, and structured evidence-backed substrate over generated markdown summaries.
+Keep the `v0.2.0` promise narrow and excellent: frictionless terminal setup, local-only privacy, safe project indexing, honest estimated savings, and structured evidence-backed substrate over generated markdown summaries.
 
 Before publishing, run: