suture-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 suture-mcp contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,246 @@
+# suture-mcp (Beta)
+
+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.**
+
+## Quickstart
+
+The beta onboarding path is terminal-first:
+
+```bash
+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:
+
+```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
+```
+
+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-mcp 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-mcp doctor
+```
+
+The printed MCP config is ready to paste into your agent:
+
+```json
+{
+  "mcpServers": {
+    "suture": {
+      "command": "suture-mcp",
+      "args": ["serve", "--dir", "/path/to/suture-data"]
+    }
+  }
+}
+```
+
+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.
+
+## Beta Install Validation
+
+Use this sequence to validate a beta install exactly like a new user would:
+
+```bash
+npx suture-mcp@beta setup --yes --project /path/to/project --dir /path/to/shared-suture-state
+npx suture-mcp@beta setup --yes --project /path/to/project --dir /path/to/shared-suture-state --json
+npx suture-mcp@beta doctor --dir /path/to/shared-suture-state
+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
+
+Suture is in **local-first beta**. 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.
+- **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.
+
+## Current Capabilities
+
+- **Structured Memory:** `remember`, `recall`, `search`, `curate`, `transfer`, `forget`, and `discovery`.
+- **Project Discovery:** Secure local scanning to build "project maps" of languages, entrypoints, and conventions.
+- **Hybrid Search:** Search across a semantic memory graph, code symbol graph, and SQLite FTS5 index.
+- **RIR Curation:** Automatic memory tiering (Core, Recall, Archive) based on Recency, Importance, and Relevance.
+- **Value Metrics:** Local-only estimates for cached substrate tokens, avoided rereads, indexed/skipped files, code symbols, substrate search hits, duplicate recall skips, and configurable token cost savings.
+- **CLI Hooks:** Integration points for agent `session-start` and `pre-compact` workflows.
+- **Terminal UI:** Boxed ASCII setup, keyboard-selectable finding curation, index previews, progress/result panels, and a stats dashboard designed for `npx suture-mcp@beta setup`.
+
+## Install
+
+```bash
+npm install -g suture-mcp
+suture-mcp setup --project /path/to/project --dir /path/to/state
+```
+
+For local development:
+
+```bash
+npm install
+npm run build
+npm test
+```
+
+## MCP Server
+
+Start the server over stdio:
+
+```bash
+suture-mcp serve --dir /path/to/state
+```
+
+Example MCP client configuration (Note: Use absolute paths; many clients do not expand `~`):
+
+```json
+{
+  "mcpServers": {
+    "suture": {
+      "command": "suture-mcp",
+      "args": ["serve", "--dir", "/home/user/.suture"]
+    }
+  }
+}
+```
+
+## CLI
+
+```bash
+suture-mcp setup [--project <path>] [--dir <state>] [--yes] [--json]
+suture-mcp init [--dir <path>]
+suture-mcp serve [--dir <path>]
+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>]
+```
+
+`index` previews by default. Persistence requires `--apply-safe`.
+
+`hook` commands expose the same session-start and compaction orchestration used by agent integrations, so shell-based clients can request setup/context blocks, force reinjection after compaction, and store compact summaries without using provider-specific glue.
+
+Beta indexing is deliberately conservative: manifest/config/script/test/code-symbol indexing is enabled, raw markdown memory generation is disabled, and secrets, `.env`, dependencies, build output, generated files, and local tool state directories are ignored.
+
+## Multi-Agent Sharing
+
+Suture memory is shared by state directory, not by model provider. Configure every agent that should share memory with the same `--dir` value:
+
+```json
+{
+  "mcpServers": {
+    "suture": {
+      "command": "suture-mcp",
+      "args": ["serve", "--dir", "/path/to/shared-suture-state"]
+    }
+  }
+}
+```
+
+When a second agent indexes the same project in the same state directory, Suture reuses the existing project substrate instead of creating a duplicate index. Project identity is derived from a stable fingerprint using, in priority order, git remote, package name, and real project path fallback. Setup shows whether it found an existing substrate, and unchanged files are skipped by content hash.
+
+This means a Claude, Codex, Cursor, or other MCP-capable client can share the same structured memory as long as they point at the same state directory.
+
+## Harness And Model Agnostic Design
+
+Suture treats models as interchangeable callers. The durable contract is structured memory plus MCP/CLI transport, not a provider-specific prompt format.
+
+- MCP tools return plain JSON payloads.
+- Hook outputs support text and JSON in addition to Claude-compatible JSON.
+- Curator logic is provider-injectable through `CuratorProvider`.
+- Persistence is local SQLite with WAL and a busy timeout, so harnesses can share memory without sharing a vendor account.
+
+Recommended integration pattern for a new harness:
+
+1. Call `recall` or `hook session-start` at session start.
+2. Call `remember` for user-approved summaries, decisions, and durable facts.
+3. Call `search` for targeted context retrieval.
+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.
+
+## Security Boundaries
+
+Suture is local-first by default. It is designed to avoid storing raw prompt transcripts and to reject obvious secrets before persistence.
+
+Current boundaries:
+
+- Obvious API keys, private keys, and environment secrets are blocked and redacted.
+- Exports are limited to the Suture state directory or `/tmp`.
+- Discovery ignores common dependency/build/cache directories.
+- The `import` MCP tool is intentionally disabled until migration-safe restore validation is implemented.
+
+These protections are defense-in-depth, not a replacement for a dedicated secret scanner. Treat team sync and remote storage as product features that require explicit review before enabling.
+
+## Product Direction
+
+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.
+- Enterprise layer: SSO, retention controls, compliance exports, private deployment, and model/harness fleet observability.
+
+The product moat is not a single model integration. It is trusted, portable, policy-aware memory that follows the work across tools.
+
+## Publishing Beta
+
+Publish beta builds 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
+```
+
+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.
+
+Before publishing, run:
+
+```bash
+npm run typecheck
+npm test
+npm run build
+node scripts/smoke-test.js
+```
+
+After publishing, validate from a clean directory:
+
+```bash
+npx suture-mcp@beta setup --yes --project "$PWD" --dir /tmp/suture-beta-verify
+npx suture-mcp@beta doctor --dir /tmp/suture-beta-verify
+npx suture-mcp@beta stats --dir /tmp/suture-beta-verify
+```
+
+## Development
+
+```bash
+npm run typecheck
+npm test
+npm run build
+npm pack --dry-run
+```
+
+The package publish surface is intentionally limited to `dist`, `README.md`, and `LICENSE`.