wyrm-mcp 7.5.0 → 7.5.2

package/COMPARISON.md

@@ -29,7 +29,7 @@ This table compares facts that mean the same thing for every system.
 
 | System | Open source | Runs fully local / no cloud | LLM at **write** (ingest) | LLM at **answer** | Headline metric |
 |---|---|---|---|---|---|
-| **Wyrm** | AGPL-3.0 (dual-licensed) | ✅ yes | ❌ **none** (deterministic FTS/vector) | ❌ **none** (retrieval only) | retrieval recall@k |
+| **Wyrm** | No (proprietary freeware) | ✅ yes | ❌ **none** (deterministic FTS/vector) | ❌ **none** (retrieval only) | retrieval recall@k |
 | Mem0 | Apache-2.0 (+ managed cloud) | self-host possible | ✅ required (LLM extraction + ADD/UPDATE/DELETE/NOOP) | ✅ required | QA accuracy (LLM-judge "J") |
 | Zep / Graphiti | Graphiti Apache-2.0 (Zep cloud) | self-host possible | ✅ required (LLM graph construction) | ✅ required | QA accuracy (LLM-judge) |
 | SuperMemory · cognee · SuperLocalMemory | varies | varies | varies | varies | *no citable LoCoMo/LongMemEval number found* (see below) |

package/README.md

@@ -1,522 +1,121 @@
-# Wyrm — the intelligence layer for AI agents
-
-> Persistent memory is table stakes. The real problem is what agents *do* with it — Wyrm blocks the repeat, keeps decisions true, and learns as a fleet. Memory is the substrate; the judgment is the moat.
-
-[![npm version](https://img.shields.io/npm/v/wyrm-mcp?color=00B89F&label=npm)](https://www.npmjs.com/package/wyrm-mcp)
-[![License: Proprietary](https://img.shields.io/badge/License-Proprietary-b91c1c.svg)](LICENSE)
-[![Tests](https://img.shields.io/badge/tests-1901%20passing-00B89F)](https://github.com/Ghosts-Protocol-Pvt-Ltd/Wyrm)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
-[![MCP](https://img.shields.io/badge/MCP-compatible-00B89F)](https://modelcontextprotocol.io)
-
-**[wyrm.ghosts.lk](https://wyrm.ghosts.lk)**  ·  **[npm](https://www.npmjs.com/package/wyrm-mcp)**  ·  **[GitHub](https://github.com/Ghosts-Protocol-Pvt-Ltd/Wyrm)**  ·  **[Ghost Protocol](https://ghosts.lk)**  ·  `npm i -g wyrm-mcp`
-
-Local-first persistent memory for AI agents over MCP — by [Ghost Protocol](https://ghosts.lk). Runs fully offline on your machine: no cloud, no LLM required. The official build activates with a one-time free `wyrm login`; your memory stays local either way. The managed cloud tier lives at **[wyrm.ghosts.lk](https://wyrm.ghosts.lk)**.
-
----
-
-## What Wyrm actually is
-
-Wyrm is not "AI memory." It's the **substrate** that turns one-shot AI conversations into *accreting intelligence*. Five things, only one of which is memory:
-
-1. **⌇ Memory across sessions, tools, and projects.** Your AI inherits prior state instead of starting cold every conversation. Works with Claude / Copilot / Cursor / Windsurf / Codex.
-2. **✖ Counter-pattern blocking.** When an approach fails, Wyrm records it. Next time, your AI is *blocked* from suggesting the same failed thing again. Other memory tools learn only from success — Wyrm learns from failure too.
-3. **→ Autonomous goal pursuit (OODA agent loop).** Set a persistent goal ("ship v2", "keep deps current weekly"), and the `wyrm-loop` daemon runs Observe→Orient→Decide→Act iterations until success criteria are met.
-4. **↯ Federation.** Wyrm calls other MCP servers (GitHub, Slack, Linear, …) as tools. Buddy Protocol v1.0 lets Wyrm talk to other AI memory tools. Composes your whole stack into one mind.
-5. **✺ Creative substrate.** First-class design tokens (colour / type / spacing / motion / shadow / radius / breakpoint) and a tagged design-reference clipper — Wyrm is not just for code.
-
-**Reproducible numbers — with receipts.** Every figure below is offline and reproducible from this repo → **[BENCHMARKS.md](BENCHMARKS.md)**:
-
-- **Retrieval** — real LoCoMo (1,982 evidence QA): the deterministic **zero-LLM, zero-cloud** floor is recall@5 **52.4%** / recall@10 **59.9%**, lifting to **60.3% / 72.2%** with local Ollama vectors.
-- **Negative learning** — the benchmark no recall-only memory runs: the firewall blocks a repeated mistake at **100% recall · 100% precision** (0 false blocks on novel actions), deterministic, p50 ~0.1 ms.
-- **Reranker (opt-in)** — a local cross-encoder lifts recall@1 **33% → 53%** (+19 pts) and MRR **.45 → .61**.
-- **Honest vs the field** → **[COMPARISON.md](COMPARISON.md)**: Wyrm reports *retrieval recall@k*; mem0 / Zep report *LLM-judged QA-accuracy* — different axes, never conflated, every competitor figure cited + vendor-self-reported.
-
-```
-You: "What did we decide about the auth architecture last week?"
-AI:  *calls wyrm_session_prime* "We went with JWT + refresh tokens, stored
-      in httpOnly cookies. Truth #142 cites the Tuesday session — there's
-      a downstream impact on the OAuth flow we should check first."
-```
-
-You don't ask for memory. The AI cites it on its own. Visibly, with sources.
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Ghosts-Protocol-Pvt-Ltd/wyrm-mcp/main/assets/dragon-mark.svg" alt="Wyrm" width="96" />
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Ghosts-Protocol-Pvt-Ltd/wyrm-mcp/main/assets/hero.svg" alt="Wyrm — memory that survives the session" width="100%" />
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/wyrm-mcp"><img src="https://img.shields.io/npm/v/wyrm-mcp?style=flat-square&labelColor=050505&color=c9ccd1&label=npm" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/wyrm-mcp"><img src="https://img.shields.io/npm/dm/wyrm-mcp?style=flat-square&labelColor=050505&color=c9ccd1&label=downloads" alt="npm downloads" /></a>
+  <a href="#requirements"><img src="https://img.shields.io/node/v/wyrm-mcp?style=flat-square&labelColor=050505&color=c9ccd1" alt="node" /></a>
+  <img src="https://img.shields.io/badge/license-proprietary-c9ccd1?style=flat-square&labelColor=050505" alt="license: proprietary" />
+  <img src="https://img.shields.io/badge/registry-lk.ghosts%2Fwyrm-34d399?style=flat-square&labelColor=050505" alt="MCP registry" />
+  <img src="https://img.shields.io/badge/runs-local--first-34d399?style=flat-square&labelColor=050505" alt="local-first" />
+</p>
+
+<p align="center">
+  <b>Persistent memory for AI agents, over MCP.</b><br/>
+  Ground truths, recorded failures that block repeats, decision causality, and hybrid recall.<br/>
+  A structured SQLite memory on your machine. No cloud, no separate LLM.
+</p>
+
+<p align="center">
+  <a href="https://ghosts.lk/wyrm">Website</a> ·
+  <a href="#quickstart">Quickstart</a> ·
+  <a href="https://github.com/Ghosts-Protocol-Pvt-Ltd/wyrm-mcp/discussions">Discussions</a> ·
+  <a href="CHANGELOG.md">Changelog</a>
+</p>
 
 ---
 
-## New in 7.0 — "BROOD": memory for agent FLEETS
+## What it is
 
-> *One agent burns its hand and a hundred siblings never touch the stove.*
+Most AI coding sessions start from zero. Wyrm gives the agent a memory that persists across them. It keeps your project's decisions, conventions, open work, and dead-ends in a structured database on your own machine, and hands them back to the model at the start of the next session. An agent connected to Wyrm recalls what was decided last week instead of re-deriving it, and can be stopped from repeating an approach that already failed.
 
-The unit of cognition is now the **run** — an orchestrator fanning out structured-output subagents — and 7.0 rebuilds Wyrm around it:
+It speaks the Model Context Protocol, so it drops into Claude, Cursor, Copilot, Windsurf, and Codex without glue code.
 
-- **The lean frozen surface.** Default ListTools advertises **32 tools** (≈7,993 tokens — chars/4, the F1-census convention — byte-stable across calls) instead of 6.x's 62-tool default / 137 full-load — and **every one of the 137 6.x names stays callable** through a generated alias spine routing to the same handlers. `WYRM_PROFILE=essential` = the core 4 (`session_prime` / `recall` / `capture` / `failure_check`); `WYRM_PROFILE=legacy` (or `full`, now its permanent synonym) re-advertises everything. Discovery is a hard CI gate: BM25 top-3 **100%** on 65 intent queries (threshold 90%).
-- **Run-native attribution.** First-class `runs`/`run_agents` tables; every write attributable to `(agent_id, run_id)` (explicit param > `_meta['wyrm/actor']` > env > clientInfo), bound into the signed Ed25519 audit chain.
-- **Fleet negative learning.** A failure recorded by one subagent **blocks the repeat for every sibling**: run-scoped quarantine with principled promotion, structured `failure_check` verdicts (`{blocked, matches[], recorded_by_agent, run_id, confidence}` — deterministic, no LLM), and **`wyrm-guard`** — a PreToolUse hook bin that enforces it harness-side (block / warn / silent when clean; measured p95 ≤70ms incl. node startup). `wyrm_stats view=failures` prints the ROI number nobody else can: *"N repeats blocked this run."*
-- **The run loop.** `wyrm_run` `action=start|join|status|debrief|end` — debrief fans each agent's learnings through LOCAL-only extraction (Ollama / deterministic fallback, never a cloud LLM) into a run-scoped review queue; `end` promotes/expires quarantined failures and releases the run's claims. Fleet-mode `session_prime {run_id, role}` returns a byte-stable cached brief (≤1,200 tokens) — 12 simultaneous primes share one prompt-cache prefix. **Distribute-once**: an orchestrator that primes one `{run_id, role, for_spawn: true}` per role gets that brief back as clean embeddable markdown (+ `brief_hash` + the `run_briefs` cache key) and embeds it in each same-role agent's spawn-prompt **prefix** — so the cacheable share of the fleet's prime cost becomes never-sent bytes (measured: a 12-agent / 4-role run's prime deliveries drop 12 → 4; bench `S3b` is −38.7% vs the `S3` floor). Agent-side prime stays the byte-identical CAS-row fallback, so a forgetful orchestrator degrades to the unchanged per-agent cost, never below.
-- **A typed machine wire.** The 7 hot-path domains (capture, recall, search, failure, quest, session/prime, review) return schema-validated `structuredContent`; `content[0].text` is *derived* from it (plain ASCII default, `WYRM_FANCY=1` for glyphs); SEP-1303 structured errors fleets self-correct on; 100% of advertised tools annotated; `prime`/`debrief` exposed as MCP protocol-level prompts.
-- **Single-channel wire (opt-in token economy).** `WYRM_CHANNEL` (vendor-neutral, set per MCP-client config) chooses which channel(s) ride the wire. Default **`both`** = today's exact bytes (no change unless you opt in). **`structured`** keeps the full `structuredContent` body byte-identical and collapses `content[0].text` to the template's summary line + a "full body in structuredContent" pointer — **lossless by construction** (the text was always *derived* from the body) and protocol-valid, but requires that your harness forwards `structuredContent` to the model. **`text`** drops `structuredContent` and keeps the full prose (the human-complete derivation) — the lean mode for harnesses that read text only; **note:** a strict MCP client rejects a body-less response for a tool that declares an `outputSchema`, so `text` is for non-strict / text-only consumers. Measured on `bench/token-economy.mjs --channel`: an opted-in working hour drops **~40%** (`structured`) to **~49%** (`text`); recall (82% of that hour) is the lever. `session_rehydrate` is exempt (its briefing markdown *is* the payload).
-- **CLI exile + deletions.** 22 operator/egress tools moved to `wyrm` subcommands — their MCP names return a structured redirect with the exact command (`wyrm_cloud_backup`/`wyrm_sync_export` keep executing through 7.0.x so scheduled backups never silently stop). The legacy `wyrm-http` server is **deleted** (its 6.18 access log measured zero traffic) — `wyrm serve` is the HTTP surface.
+## Quickstart
 
-**Compatibility:** all 137 names callable; text output reformats (exact-string consumers pin the 6.x line — kept on the `legacy` dist-tag (`wyrm-mcp@6.18.1`): `npm i wyrm-mcp@legacy`); a v6.x database opens with 100% rows (migrations 20–24, all additive + guarded). Per-name dispositions: `specs/wyrm-v7-brood/disposition.md` in the repo.
-
-## New in 6.0 — "Present"
-
-- **Live statusline** — `wyrm-statusline` binary renders Wyrm's live state into your Claude Code (or Cursor / Windsurf) statusline: `Wyrm · ProjectName · 3 ⟶ · ~12k saved · ⬢ 7`. Auto-spawned daemon, idle-times-out, privacy mode for screen-shares.
-- **✧ Cross-project memory** — `wyrm_constellation` queries FTS5 across every registered Wyrm project at once. *"Have I solved this before in any project?"* Privacy-gated: per-row `cross_project_visibility` defaults to `'within'`.
-- **▰ Tool profiles** — `essential` / `standard` / `full` profiles. *(7.0: client-name auto-detection removed — `WYRM_PROFILE` is the one lever; `full` = `legacy`.)*
-- **⊡ Cache markers** — `wyrm_context_build` segregates a stable preamble for Anthropic prompt-caching (10× cost cut on cached portions).
-- **↺ `wyrm_migrate_prompt`** — rewrite Wyrm-managed blocks in `.cursor/rules`, `.github/copilot-instructions.md`, `CLAUDE.md` idempotently. Operator content outside the markers is preserved verbatim.
-
-Enable the statusline in Claude Code:
-```json
-{ "statusLine": { "type": "command", "command": "wyrm-statusline", "padding": 0 } }
-```
-
-## What's in the box (32 advertised tools · 137 names callable)
-
-- **⌇ Memory** — projects, sessions, quests, ground truths, memory artifacts, hybrid FTS5 + vector search
-- **✖ Counter-pattern** — failure check / record / resolve, blocks repeated mistakes at suggestion time
-- **⬢ Ground truths** — validated facts versioned with cascade-invalidation when upstream changes
-- **✱ Decision chain** — `wyrm_decided_because`, `decision_upstream` / `_downstream`, blast-radius traversal
-- **→ Agent loop** — `wyrm_goal_set`, `wyrm_agent_init`, daemon runs OODA until success criteria are met
-- **↯ Federation** — `wyrm_mcp_register` for outbound MCP, Buddy Protocol v1.0 for peer AI tools
-- **🕸 Knowledge graph** — entity / relationship graph with shortest-path and neighborhood queries
-- **🎨 Design substrate** — `design_tokens` + tagged `design_references` library
-- **🛡 Audit chain** — hash-chained, Ed25519-signable audit log for SOC2 / HIPAA
-- **💰 Hour ledger + invoicing** — generate invoices from session content
-- **🌐 Federated team sync** — per-row `is_shared` flag; PII never leaves your box unless explicitly shared
-- **🔒 Encryption** — AES-256-GCM; keys never leave your machine
-- **👁 Visibility tools** — `wyrm_intro` + `wyrm_digest` make Wyrm's work product legible to humans
-
-## Built for these workflows
-
-- **Founders** with multi-product portfolios — cross-project memory makes patterns from project A inform project B
-- **Designers / creatives** — design tokens + reference clipper turn Wyrm into a creative substrate, not just a code-memory tool
-- **Co-founders / operators** — `wyrm_digest` shows what Wyrm did this week in plain English
-- **Long-running autonomous work** — agent loop runs your standing goals overnight
-- 🧠 **Memory Artifacts** — Store lessons, patterns, anti-patterns, heuristics with confidence scoring and lifecycle tracking
-- 🧱 **Ground Truths** — Versioned, validated project facts injected into every AI context build
-- 🧭 **Reasoning Scaffolds** — Structured checklists surfaced automatically when task type matches
-- 🔬 **Distillation Queue** — Batch-extract session knowledge into reviewed, curated memory
-- 🔍 **Hybrid Search** — Reciprocal Rank Fusion combining FTS5 + vector candidates
-
----
-
-## Installation
-
-### npm (recommended)
 ```bash
-npm install -g wyrm-mcp
+npm install -g wyrm-mcp   # install
+wyrm-setup                # wire it into your AI clients, then restart them
 ```
 
-### Homebrew (macOS / Linux)
-```bash
-brew tap ghosts-lk/wyrm
-brew install wyrm-mcp
-```
+Then, from inside your client, ask it to call `wyrm_capabilities` to confirm the connection. The everyday loop is four steps the agent runs on its own once the habit sets in:
 
-### Docker
-```bash
-docker run -d -p 3000:3000 -v wyrm-data:/data ghcr.io/ghosts-lk/wyrm-mcp:latest
 ```
-Or with Docker Compose:
-```bash
-curl -O https://raw.githubusercontent.com/Ghosts-Protocol-Pvt-Ltd/Wyrm/main/docker-compose.yml
-docker compose up -d
+prime    →  load the project's truths, quests, and dead-ends at session start
+recall   →  retrieve what you know before re-deriving it
+check    →  before retrying an approach, ask if it already failed
+capture  →  store durable facts, lessons, and tasks as you go
 ```
 
-### npx (no install)
-```bash
-npx wyrm-mcp
-```
-
----
-
-## Quick Start
-
-### 1. Install
-
-```bash
-npm install -g wyrm-mcp
-```
-
-### 2. Connect to Your AI
-
-Add Wyrm to your AI client's MCP configuration:
-
-<details>
-<summary><strong>Claude Desktop</strong></summary>
-
-Edit `~/.config/claude/claude_desktop_config.json` (Linux) or `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):
-
-```json
-{
-  "mcpServers": {
-    "wyrm": {
-      "command": "wyrm-mcp"
-    }
-  }
-}
-```
+## Measured, not asserted
 
-</details>
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Ghosts-Protocol-Pvt-Ltd/wyrm-mcp/main/assets/receipt.svg" alt="Wyrm measured receipt" width="720" />
+</p>
 
-<details>
-<summary><strong>GitHub Copilot (VS Code)</strong></summary>
+Every number Wyrm publishes comes from a benchmark committed to the source, reproducible on your own data. The negative-learning firewall and the recall lift are the two that matter most, and both are covered below.
 
-Add to `.vscode/settings.json` or your user settings:
+## Why Wyrm
 
-```json
-{
-  "mcp": {
-    "servers": {
-      "wyrm": {
-        "command": "wyrm-mcp"
-      }
-    }
-  }
-}
-```
-
-</details>
-
-<details>
-<summary><strong>GitHub Copilot CLI</strong></summary>
-
-Add to `~/.copilot/mcp-config.json`:
-
-```json
-{
-  "mcpServers": {
-    "wyrm": {
-      "command": "wyrm-mcp"
-    }
-  }
-}
-```
-
-</details>
+### It remembers what failed, not just what worked
 
-<details>
-<summary><strong>Cursor</strong></summary>
+Most memory tools store successes. Wyrm also records dead-ends and blocks the repeat. You record a failed approach with `wyrm_failure_record`, and a later `wyrm_failure_check` surfaces it before the agent walks back into it. Across a session that stops re-litigating solved problems; across a fleet of agents, one worker's dead-end warns the rest, once.
 
-Add to `~/.cursor/mcp.json`:
+### Recall that finds things by meaning, not just keywords
 
-```json
-{
-  "mcpServers": {
-    "wyrm": {
-      "command": "wyrm-mcp"
-    }
-  }
-}
-```
-
-</details>
+`wyrm_recall` runs keyword search (FTS5) and semantic search over a vector index, fuses them, and reranks. It is hybrid by default, no configuration required. For higher accuracy you can opt into NVIDIA NIM retrieval (below).
 
-<details>
-<summary><strong>Windsurf</strong></summary>
+### Local-first, and honest about egress
 
-Add to `~/.codeium/windsurf/mcp_config.json`:
-
-```json
-{
-  "mcpServers": {
-    "wyrm": {
-      "command": "wyrm-mcp"
-    }
-  }
-}
-```
+By default nothing leaves your machine. The database is a single SQLite file at `~/.wyrm/wyrm.db`. When you do opt into a hosted embedding path, Wyrm reports exactly what left and where, in a determinism receipt and on its health endpoint. The privacy claim is one you can verify from the runtime, not just the docs.
 
-</details>
+### Built for one agent or a fleet
 
-Or run **`wyrm-setup`** to auto-detect and configure every supported AI client at once (VS Code Copilot, Claude Desktop, Cursor, Windsurf, Zed, Continue, plus Claude Code hooks).
+Every memory is attributed to the agent and run that produced it, so a swarm of agents can share one accountable memory bus, with failures kept private to your account by default. A live event stream keeps devices in sync.
 
-### 3. Enable Semantic Search (Optional but Recommended)
+## NVIDIA NIM retrieval (optional)
 
-Wyrm uses hybrid search (FTS5 + semantic vectors) when [Ollama](https://ollama.com) is running locally. No configuration needed — Wyrm auto-detects it.
+Wyrm can use NVIDIA NIM for embeddings and reranking when accuracy is worth a hosted call. On a retrieval benchmark committed in the repo, recall@1 moved from 33% on the local baseline to 47% with NIM embeddings and 52% with NIM reranking added. It is an explicit opt-in, off by default, and the egress is disclosed on every call.
 
 ```bash
-# Install Ollama: https://ollama.com
-ollama pull nomic-embed-text
+export WYRM_VECTOR_PROVIDER=nim
+export WYRM_RERANK_PROVIDER=nim
+export NIM_API_KEY=nvapi-...
 ```
 
-That's it. Once `nomic-embed-text` is available, `wyrm_search` automatically upgrades from keyword-only to hybrid semantic+keyword search using Reciprocal Rank Fusion. If Ollama isn't running, Wyrm falls back to FTS5 silently — no errors, no config changes required.
+<sub>Ghost Protocol (Pvt) Ltd is a member of NVIDIA Inception.</sub>
 
-To use OpenAI embeddings instead:
-```bash
-WYRM_VECTOR_PROVIDER=openai OPENAI_API_KEY=sk-... wyrm-mcp
-```
+## Works with
 
-### 4. Use It
+Claude (Code, desktop, web) · Cursor · GitHub Copilot · Windsurf · Codex, and any MCP-capable client.
 
-Once connected, your AI has access to all Wyrm tools. Try:
+## Requirements
 
-```
-"Scan ~/projects for git repositories"
-"Start a session for my auth refactor"
-"What quests are pending across all projects?"
-"Search my memory for anything about database migrations"
-```
-
----
-
-## MCP Tools Reference
-
-Wyrm exposes a frozen 32-verb typed surface (137 tools callable) via the Model Context Protocol:
-
-### Projects
-
-| Tool | Description |
-|------|-------------|
-| `wyrm_scan_projects` | Discover git projects in a directory tree |
-| `wyrm_list_projects` | List all registered projects with metadata |
-| `wyrm_project_context` | Get full context for a project (sessions, quests, data) |
-| `wyrm_global_context` | Overview across all projects |
-
-### Sessions
-
-| Tool | Description |
-|------|-------------|
-| `wyrm_session_start` | Start or continue a named session with context |
-| `wyrm_session_update` | Update session with completed work, decisions, and notes |
-
-### Quests (Task Tracking)
-
-| Tool | Description |
-|------|-------------|
-| `wyrm_quest_add` | Add a task with priority, tags, and description |
-| `wyrm_quest_complete` | Mark a task as done with completion notes |
-| `wyrm_all_quests` | List pending tasks across all projects |
-
-### Data Lake
-
-| Tool | Description |
-|------|-------------|
-| `wyrm_data_insert` | Store a data point with namespace and metadata |
-| `wyrm_data_batch_insert` | Bulk insert for large datasets |
-| `wyrm_data_query` | Query stored data by namespace, key, or content |
-| `wyrm_data_categories` | List all data categories for a project |
-
-### Skills Registry
-
-| Tool | Description |
-|------|-------------|
-| `wyrm_skill_register` | Register or update a skill with metadata |
-| `wyrm_skill_list` | List skills with filtering options |
-| `wyrm_skill_get` | Get detailed skill information |
-| `wyrm_skill_search` | Search skills by name, description, or tags |
-| `wyrm_skill_activate` / `wyrm_skill_deactivate` | Toggle skill status |
-| `wyrm_skill_delete` | Remove a skill |
-| `wyrm_skill_stats` | Skill registry statistics |
-
-### Search & Utilities
-
-| Tool | Description |
-|------|-------------|
-| `wyrm_search` | Full-text search across all projects, sessions, quests, and data |
-| `wyrm_set_global` | Set global context that applies across all projects |
-| `wyrm_sync` | Sync database with `.wyrm/` markdown files |
-| `wyrm_stats` | Database statistics and health |
-| `wyrm_usage` | Token usage stats, cache hit rates, and cost estimates |
-| `wyrm_maintenance` | Vacuum, archive old data, optimize indexes |
-| `wyrm_setup` | Auto-configure Wyrm in every supported AI client it detects |
-
-### Auto-Orchestration
-
-| Tool | Description |
-|------|-------------|
-| `wyrm_orchestrate_task` | Classify a task and get an orchestration plan |
-| `wyrm_orchestration_config` | View or update orchestration settings |
-| `wyrm_orchestration_stats` | Orchestration effectiveness and task distribution |
-
-### Knowledge Graph
-
-| Tool | Description |
-|------|-------------|
-| `wyrm_entity_add` | Add a named entity to the project's knowledge graph |
-| `wyrm_entity_link` | Create a typed, directional relationship between two entities |
-| `wyrm_entity_search` | Find entities by name or alias |
-| `wyrm_entity_graph` | Get the neighborhood graph around an entity (recursive traversal) |
-| `wyrm_entity_path` | Find shortest path between two entities |
-| `wyrm_entity_merge` | Merge two duplicate entities, consolidating aliases and relationships |
-
-### Memory Artifacts
-
-| Tool | Description |
-|------|-------------|
-| `wyrm_remember` | Store a distilled memory artifact — pattern, lesson, anti-pattern, heuristic, or reasoning trace |
-| `wyrm_recall` | Retrieve relevant memory artifacts for a task — hybrid FTS5 + local-vector retrieval (convex score blend) when embeddings are available, lexical+tag fallback offline |
-| `wyrm_feedback` | Record whether a recalled artifact was helpful (updates confidence via Bayesian adjustment) |
-| `wyrm_context_build` | Assemble a task-specific context brief: ground truths + best scaffold + relevant memory artifacts |
-
-### Intelligence Amplification
-
-| Tool | Description |
-|------|-------------|
-| `wyrm_truth_set` | Store a validated ground truth (architecture, constraints, decisions) — versioned, history preserved |
-| `wyrm_truth_get` | Retrieve all current ground truths for a project, optionally filtered by category |
-| `wyrm_scaffold_save` | Save a reasoning scaffold — structured step-by-step checklist for a problem type |
-| `wyrm_scaffold_get` | Find the best matching reasoning scaffold for a task description |
-| `wyrm_distill` | Queue candidate memory artifacts from a session for human review |
-| `wyrm_review` | Approve (activate) or reject (permanently delete) any queued review candidate — from auto-capture, harvest, capture conflict-routing, imports, or distillation |
-
----
-
-## Configuration
-
-### Environment Variables
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `WYRM_DB_PATH` | `~/.wyrm/wyrm.db` | SQLite database location |
-| `WYRM_ENCRYPTION_KEY` | *(none)* | AES-256-GCM encryption key for sensitive data |
-| `WYRM_LOG_LEVEL` | `info` | Logging level (`debug`, `info`, `warn`, `error`) |
-| `WYRM_HTTP_PORT` | `3333` | HTTP API server port |
-
-### Encryption
-
-To enable encryption for sensitive context data:
-
-```bash
-# Generate a key
-openssl rand -hex 32
-
-# Set it before starting Wyrm
-export WYRM_ENCRYPTION_KEY="your-64-char-hex-key"
-```
-
-All encryption happens locally. Keys never leave your machine.
-
-### Per-Project Files
-
-Each tracked project gets a `.wyrm/` directory:
-
-```
-project/
-└── .wyrm/
-    ├── hoard.md        # Project knowledge — architecture, decisions, context
-    ├── chronicles.md   # 📜 Session history — what was discussed and built
-    ├── quests.md       # ⚔️ Task queue — pending and completed work
-    └── protocol.md     # 🔥 AI guidelines — project-specific instructions
-```
-
-These sync bi-directionally with the SQLite database via `wyrm_sync`.
-
----
-
-## Architecture
-
-```
-┌─────────────────────────────────────────────────────────┐
-│                    AI Assistants                         │
-│     (Copilot · Claude · Cursor · Windsurf · Zed)        │
-└────────────────────────┬────────────────────────────────┘
-                         │ MCP (stdio)
-                         ▼
-┌─────────────────────────────────────────────────────────┐
-│                  Wyrm MCP Server                        │
-│                                                         │
-│  ┌──────────────────────────────────────────────────┐   │
-│  │  Intelligence Layer                               │   │
-│  │  Ground Truths · Reasoning Scaffolds · Distill    │   │
-│  └──────────────────────────────────────────────────┘   │
-│  ┌──────────────────────────────────────────────────┐   │
-│  │  Memory Artifacts · Knowledge Graph               │   │
-│  └──────────────────────────────────────────────────┘   │
-│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌────────┐  │
-│  │ Projects │  │ Sessions │  │  Quests  │  │ Skills │  │
-│  └──────────┘  └──────────┘  └──────────┘  └────────┘  │
-│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌────────┐  │
-│  │ DataLake │  │  Hybrid  │  │  Crypto  │  │  Sync  │  │
-│  │          │  │  Search  │  │(AES-256) │  │  (.md) │  │
-│  └──────────┘  └──────────┘  └──────────┘  └────────┘  │
-│                                                         │
-│              SQLite Database (WAL mode)                  │
-│              Optional HTTP API (:3333)                   │
-└─────────────────────────────────────────────────────────┘
-```
+Node.js 22 or newer. Optional: a local Ollama with `nomic-embed-text` for semantic recall without any hosted call.
 
-**Stack:** TypeScript · Node.js · better-sqlite3 · FTS5 · MCP SDK
+## Community and feedback
 
----
-
-## Development
-
-```bash
-# Clone and install
-git clone https://github.com/Ghosts-Protocol-Pvt-Ltd/Wyrm.git
-cd Wyrm/packages/mcp-server
-npm install
-
-# Build
-npm run build
-
-# Run tests
-npm test
-
-# Watch mode
-npm run dev
-```
-
-### Project Structure
-
-```
-Wyrm/
-├── packages/
-│   ├── mcp-server/          # Core MCP server
-│   │   ├── src/
-│   │   │   ├── index.ts     # MCP tool definitions & server
-│   │   │   ├── database.ts  # SQLite schema & queries
-│   │   │   ├── crypto.ts    # AES-256-GCM encryption
-│   │   │   ├── security.ts  # Input sanitization
-│   │   │   └── ...
-│   │   ├── tests/           # Jest test suite
-│   │   └── package.json
-│   └── vscode-extension/    # VS Code extension (optional)
-├── config/                  # Configuration templates
-├── templates/               # Project template files
-├── docs/                    # Documentation
-├── examples/                # Usage examples
-└── scripts/                 # Utility scripts
-```
-
----
+Wyrm sends no telemetry, so the way we learn what is working is you telling us.
 
-## Contributing
+- **`wyrm feedback`** from your terminal opens a prefilled report. Add `--bug`, `--idea`, or `--question`.
+- **[Discussions](https://github.com/Ghosts-Protocol-Pvt-Ltd/wyrm-mcp/discussions)** for questions, ideas, and how it is going.
+- **[Issues](https://github.com/Ghosts-Protocol-Pvt-Ltd/wyrm-mcp/issues)** for bugs and concrete requests.
+- Email [ryan@ghosts.lk](mailto:ryan@ghosts.lk).
 
-Wyrm is a **proprietary repository** — free to use, but not open to external contributions. We do **not** accept forks or external pull requests.
-
-Issues and bug reports are welcome: please open an issue or email ryan@ghosts.lk.
-
----
-
-## Security
-
-- **Local-only** — All your data stays on your machine. The only default outbound call is a once-a-day npm version check (no data sent beyond the request itself; opt out with `WYRM_NO_VERSION_CHECK=1`).
-- **No telemetry** — Zero data collection, zero phone-home.
-- **Optional encryption** — AES-256-GCM for sensitive context data.
-- **Audited** — Security audits documented in [SECURITY_AUDIT.md](SECURITY_AUDIT.md) and [SECURITY_AUDIT_V2.md](SECURITY_AUDIT_V2.md).
-
-Found a vulnerability? Please open an issue or email ryan@ghosts.lk.
-
----
+If Wyrm earned a place in your workflow, a star helps other people find it.
 
 ## License
 
-**Open standard + protected implementation:**
-
-- **The Wyrm Memory Protocol** ([`PROTOCOL.md`](../../PROTOCOL.md)) is an **open spec, freely implementable** by anyone (CC-BY-4.0) — build a WMP-compatible memory without touching Wyrm's code.
-- **This implementation** (`wyrm-mcp`) is **[Proprietary Freeware](LICENSE)** — free to use, all rights reserved. Copyright © 2024-2026 [Ghost Protocol (Pvt) Ltd](https://ghosts.lk).
-
-For a **commercial license** (embedding Wyrm in a closed product, or running it as a managed service), contact [ryan@ghosts.lk](mailto:ryan@ghosts.lk).
-
----
-
-<div align="center">
-
-*The dragon remembers.*
+Wyrm is proprietary software, free to use under the [Wyrm license](LICENSE) and Terms of Service. This repository is the public home for the docs, the changelog, and the community. The source is not published here. For a commercial license (embedding Wyrm in a closed product, or running it as a managed service), contact [ryan@ghosts.lk](mailto:ryan@ghosts.lk).
 
-Built by [Ghost Protocol](https://ghosts.lk)
+<br/>
 
-</div>
+<p align="center">
+  <sub>Built by <a href="https://ghosts.lk">Ghost Protocol</a> · Colombo, Sri Lanka</sub><br/>
+  <sub>NVIDIA, the NVIDIA logo, and NVIDIA Inception are trademarks and/or registered trademarks of NVIDIA Corporation.</sub>
+</p>