mnemos-capture 1.1.0 → 1.2.1

package/README.md

@@ -10,11 +10,28 @@
   <img src="https://img.shields.io/badge/MCP-compatible-green" alt="MCP" />
 </p>
 
-<p align="center"><strong>A knowledge pipeline for AI agents.<br />Capture anything — your agents retrieve and apply it.</strong></p>
+<p align="center"><strong>Capture anything. Your agents apply it.</strong></p>
 
-Your agents only know what they were trained on. They don't know what you read this morning, what framework you found last week, or what idea you had at midnight.
+<p align="center">
+  Humans consume information. Agents execute information.<br/>
+  <em>Mnemos converts one into the other.</em>
+</p>
+
+<p align="center">A knowledge pipeline that turns what you learn into actionable context for AI agents.</p>
+
+---
+
+Your agent only knows what it was trained on. It doesn't know the article you read this morning, the framework you found last week, or the decision you made last sprint.
 
-Mnemos bridges that gap. It's a knowledge base that grows in real time and plugs directly into any agent via MCP — so every insight you capture is immediately available to every agent you use.
+**Mnemos bridges that gap.**
+
+Capture an insight once. Mnemos extracts it, stores it as plain Markdown in your own GitHub repository, indexes it, and serves it to any MCP-compatible agent.
+
+Then it goes further. At session start, Mnemos briefs your agent on what matters right now, surfaces relevant knowledge in context, synthesizes reusable rules, and turns insights into implementation plans.
+
+> **The result isn't another knowledge base.** It's a system that transforms what you learn into what your agents can execute.
+
+<p align="center"><sub>Works with <strong>Claude Code</strong> · <strong>Codex</strong> · <strong>Cursor</strong> · <strong>Gemini</strong> · and any MCP-compatible assistant.</sub></p>
 
 
 ## Get started
@@ -26,141 +43,120 @@ Go to **[mnemos-capture.vercel.app](https://mnemos-capture.vercel.app)** → **S
 During setup, Mnemos will:
 
 - Create a knowledge repo in your GitHub account — plain Markdown files, no proprietary format
-- Ask for your Anthropic API key — your key, stored per-user, Mnemos never pays for your API calls
+- Ask for your API key (your provider, your key — Mnemos never pays for your API calls)
 - Set a PIN so you can unlock the app quickly on mobile
 
 No config files. No repos to clone. No CLI setup required.
 
-### 2. Capture something
-
-Open the app on any device — phone, tablet, or desktop. Paste any content and hit **Capture**.
-
-The result is a structured Markdown file, auto-committed to your GitHub knowledge repo and immediately available to your agents.
+### 2. Connect to your AI assistant
 
-### 3. Connect to Claude Code
+When you finish onboarding, Mnemos generates a personal **MCP API key** — copy it.
 
-After signing up, you get an MCP API key. Run this once on your machine:
+**Claude Code:**
+```bash
+claude mcp add mnemos -- npx -y mnemos-capture@latest serve-mcp --key <your-mcp-key>
+```
 
+**Any MCP-compatible client** (Cursor, Continue, Gemini CLI, etc.) — point it at the stdio proxy:
 ```bash
-claude mcp add mnemos -- npx -y mnemos-capture@latest serve-mcp --key <your-api-key>
+npx -y mnemos-capture@latest serve-mcp --key <your-mcp-key>
 ```
 
-Your agent confirms the connection and can immediately access your knowledge base.
+The proxy forwards your agent's MCP tool calls to the hosted Mnemos API. Nothing is stored locally — your knowledge lives in your GitHub repo.
 
-> `npx -y mnemos-capture@latest serve-mcp` runs a lightweight local process that bridges Claude Code to the Mnemos API. The `@latest` tag guarantees you always run the most recently published version. As a safety net, the MCP server also self-upgrades on startup: if a newer version is on npm, it respawns under `npx @latest` automatically — so existing users who registered without `@latest` pick up updates on their next session. No data is stored locally — everything lives in your GitHub repo.
+### 3. Capture something
 
-**Proactive inbox notifications (automatic).** The first time the MCP server starts, Mnemos silently installs a `SessionStart` hook in `~/.claude/settings.json`. From then on, every new Claude Code session opens with a short reminder:
+Open the app on any device — phone, tablet, or desktop. Paste any content and hit **Capture**. Or capture directly from your agent:
 
 ```
-Mnemos: 3 captures in inbox — run list_inbox to review
+capture "The Mom Test — don't ask if your idea is good, ask about their life."
 ```
 
-Your agent sees this before the conversation begins and can proactively surface pending captures instead of waiting for you to ask. The hook is skipped if one already exists, so rotating keys or upgrading modes is always safe — your configuration is never overwritten silently.
-
-**Upgrade to a full session briefing (optional).** If you want more than a count — an LLM-composed briefing grounded in your current git branch, recent commits, and `CLAUDE.md` — run:
-
-```bash
-npx -y mnemos-capture@latest setup-hooks --key <your-api-key> --briefing
-```
-
-Each session now starts with a focused summary: which captures are relevant to what you're working on right now, which synthesized rules apply, and what's waiting in your inbox. Adds ~5s to session start (calls `briefing` on the hosted API, uses your Anthropic key).
-
-**Where the hook runs.** `SessionStart` hooks fire anywhere Claude Code reads your local settings — CLI, VS Code / JetBrains extensions, and the desktop app. For Claude Code on the web or other MCP clients (Cursor, etc.), the MCP tools (`list_inbox`, `briefing`, `recall`, …) still work — you just won't get the proactive nudge automatically. Add a line to that project's `CLAUDE.md` like `"At session start, call list_inbox to surface pending captures"` for a portable alternative.
-
-### 4. Connect to any MCP-compatible agent
-
-Your knowledge lives in a standard GitHub repo. Any agent that can read Git or speak MCP can access it — no lock-in, no custom integration required.
+That's it. Your knowledge is now indexed and available to every agent session.
 
 
 ## How it works
 
 ```mermaid
 flowchart TD
-    A["Article / research /\ntranscript / idea"] -->|paste| B["Mnemos\n(web / mobile / CLI)"]
-    B -->|extracts insights| C["Structured knowledge\n+ where to apply it"]
-    C -->|auto-commit| D["Your GitHub repo\n(Markdown)"]
-    D -->|MCP| E["Agent retrieves\n& surfaces to you"]
-    E -->|you decide| F{"Apply?"}
-    F -->|yes| G["Applied to\nyour workflow"]
-    F -->|no| H["Stays in\nknowledge base"]
+    A["Article / research /\ntranscript / idea"] -->|paste| B["Mnemos\n(web / mobile / agent)"]
+    B -->|extracts insight| C["Structured Markdown\ncommitted to your repo"]
+    C -->|session start| D["Briefing\nranked suggestions + plan"]
+    D -->|generate_plan| E["Implementation plan\nsaved to plans/"]
+    E -->|mnemos kos| F["Your AI assistant\nexecutes in isolated worktree"]
+    F -->|verify| G["Branch ready\nto review & merge"]
 
     style A fill:#1a1a2e,stroke:#444,color:#fff
     style B fill:#2A62C6,stroke:#1a4a9e,color:#fff
-    style C fill:#d4a843,stroke:#b8912e,color:#fff
-    style D fill:#2d8a4e,stroke:#1e6b3a,color:#fff
-    style E fill:#1a1a2e,stroke:#444,color:#fff
-    style F fill:#2A62C6,stroke:#1a4a9e,color:#fff
+    style C fill:#2d8a4e,stroke:#1e6b3a,color:#fff
+    style D fill:#d4a843,stroke:#b8912e,color:#fff
+    style E fill:#2A62C6,stroke:#1a4a9e,color:#fff
+    style F fill:#1a1a2e,stroke:#444,color:#fff
     style G fill:#2d8a4e,stroke:#1e6b3a,color:#fff
-    style H fill:#1a1a2e,stroke:#444,color:#fff
 ```
 
-1. **You paste content** — an article, a research paper, a thread, a transcript, your own ideas. Anything text-based.
-2. **Mnemos extracts the insight** — Claude Haiku 4.5 pulls the core idea (not a summary), identifies key takeaways, and tags where it could apply in your work. All automatic.
-3. **It's committed to your repo** — a structured Markdown file lands in your GitHub knowledge repo, searchable and version-controlled.
-4. **Your agents retrieve it** — Claude Code or any MCP-compatible agent can search your knowledge base and surface the right insight when it's relevant. You review, you decide what gets applied.
+1. **Capture** — paste anything text-based. Mnemos extracts the core idea, key takeaways, where to apply it, and auto-detects whether it's a URL, short note, or long paste. Committed to your GitHub repo as structured Markdown.
+2. **Brief** — at session start, the `--briefing` flag sends your project context (branch, recent commits, CLAUDE.md) to Mnemos. It returns ranked suggestions — *why* each insight matters now, *what* applying it achieves, *where* in your codebase.
+3. **Plan** — `generate_plan` reads your selected captures and produces a structured Markdown plan: Codebase Mapping table, per-file steps with effort tiers (`simple` / `complex` / `architectural`), and a Verification Checklist.
+4. **Execute** — `mnemos kos` (coming) creates an isolated git worktree, launches your configured AI assistant with the plan as its contract, and runs the verification checklist when it's done.
 
-### Example output
 
-Paste a research post about multi-agent systems. This is what gets committed to your repo:
+## What you can feed it
+
+If it's text, Mnemos can extract insight from it. No manual tagging required.
+
+- **Research papers and preprints** — new models, architectures, evaluation methods
+- **Framework and library docs** — patterns, APIs, integration approaches worth keeping
+- **Technical threads and writeups** — the argument or finding, not the noise
+- **Optimization techniques** — prompt engineering, caching strategies, latency improvements
+- **Your own ideas** — architecture decisions, workflow changes, things you want your agents to act on later
+- **Transcripts and talks** — signal extracted, ready to apply
+
+
+## Example capture
+
+Paste a research post about error observability. This is what lands in your repo:
 
 ```markdown
 ---
-date: 2026-04-01
-source: Why Multi-Agent Systems Outperform Single-Agent Loops
-url: https://example.com/multi-agent-systems
+date: 2026-06-05
+source: Error Context First — Observability for AI Systems
+url: https://example.com/error-context
 type: post
-tags: multi-agent, orchestration, agent-design, ai-architecture
+source_type: url
+tags: observability, error-handling, ai-agents, debugging
 status: inbox
+lowConfidence: false
 ---
 
-# Why Multi-Agent Systems Outperform Single-Agent Loops
+# Error Context First — Observability for AI Systems
 
 ## Core idea
-Decomposing complex tasks across specialized agents reduces error propagation
-and improves output quality — a single orchestrator routing to focused subagents
-consistently outperforms one generalist agent handling everything sequentially.
+Opaque error messages make every fix a guess. Adding source context to every
+error — which handler, which step, which input — turns debugging from archaeology
+into a directed search.
 
 ## Key takeaways
-- Specialized agents outperform generalist agents on tasks requiring depth over breadth
-- Parallel execution across subagents reduces total latency by 40-60% on multi-step tasks
-- Orchestrator-subagent patterns improve error isolation — one agent failing doesn't
-  collapse the entire workflow
-
-## Quotes
-> "The bottleneck in complex agentic tasks is not model capability — it's
-> error propagation across sequential steps."
+- Every catch block should prefix messages with where it came from
+- "The string did not match the expected pattern" is useless; "[github-write] ..." is actionable
+- Instrument before you fix — opaque errors cause repeated misdiagnoses
 
 ## Applied to
-Evaluate your current single-agent workflows for tasks that could be decomposed
-into parallel subagent calls — prioritize anything with 3+ sequential steps.
+Add handler-name prefixes to every catch block in your agent's tool pipeline.
 ```
 
-Every field is designed to help your agents find and apply the right knowledge at the right time. The **"Applied to"** field is the most important — it connects the insight to a concrete action in your work.
-
-
-## What you can feed it
-
-If it's text, Mnemos can extract insight from it. You don't need to categorize or tag anything yourself — that happens automatically.
-
-- **Research papers and preprints** — new models, architectures, evaluation methods
-- **Framework and library docs** — patterns, APIs, integration approaches worth keeping
-- **Optimization techniques** — prompt engineering, caching strategies, latency improvements
-- **Technical threads and writeups** — the argument or finding, not the noise
-- **Your own ideas** — workflow improvements, architecture decisions, things you want your agents to act on later
-- **Transcripts and talks** — the signal extracted, ready to apply
+`source_type` is auto-detected (`url` / `note` / `paste`). `lowConfidence` flags short or ambiguous input for review before acting on it.
 
 
 ## Knowledge lifecycle
 
-Knowledge that sits unreviewed rots. Mnemos forces a decision: apply it, save it for later, or discard it.
-
 ```
   ┌─────────┐
   │  Capture │
   └────┬─────┘
        ▼
   ┌─────────┐     ┌──────────┐
-  │  Inbox   │────▶│  Applied  │   You used the insight in your workflow
+  │  Inbox   │────▶│  Applied  │   Insight used — plan executed, rule added, code changed
   └────┬─────┘     └──────────┘
        │
        ├──────────▶┌──────────┐
@@ -172,67 +168,152 @@ Knowledge that sits unreviewed rots. Mnemos forces a decision: apply it, save it
                    └──────────┘
 ```
 
-**How it works in practice:**
+All captures are tracked in `INDEX.md` — a master table your agents search across your entire knowledge base. Generated plans land in `plans/`.
 
-1. **Capture** — every new capture lands in `inbox/`. After each capture, Mnemos tells you how many items are waiting for review.
-2. **Review** — use `list_inbox` to see what's in your inbox (with summaries), and `read_capture` to read the full content of any capture.
-3. **Apply** — when you've used an insight (added it to a project file, changed a workflow, created a rule), use `apply_capture` to move it to `applied/`. This closes the loop — the knowledge is now part of your system.
-4. **Archive** — reviewed it but it's not actionable right now? Use `archive_capture` to move it to `archived/`. It stays searchable but out of your inbox.
-5. **Delete** — not useful? Use `delete_capture` to permanently remove it.
 
-All captures are tracked in `INDEX.md` — a master table your agents use to search across your entire knowledge base.
+## Session hooks
+
+`serve-mcp` writes a `SessionStart` hook to `~/.claude/settings.json` on first run. Every session opens with your inbox count:
+
+```
+Mnemos: 4 captures in inbox — run list_inbox to review
+```
+
+### Briefing mode
+
+Opt in for a structured briefing instead of a count:
+
+```bash
+npx -y mnemos-capture@latest setup-hooks --key YOUR_KEY --briefing
+```
+
+At session start, Mnemos collects your project context — branch, recent commits, CLAUDE.md excerpt — and returns:
+
+1. Ranked suggestions with `why`, `benefit`, `where`, and whether to apply now
+2. Relevant synthesized rules
+3. A `generate_plan` prompt pre-loaded with the captures to apply
+
+```
+3 insights to apply now:
+
+1. error-context-first → src/app/api/capture/route.ts
+   Why: Your current branch rewrites the capture pipeline and all catch blocks are opaque
+   Benefit: Every error will identify its source in < 1 line
+
+Run generate_plan with selected_captures: ["inbox/2026-06-05-error-context-first.md"]
+```
+
+### Vault mode (PreToolCall hook)
+
+Surfaces relevant captures *before* you edit a file — not just at session start:
+
+```bash
+npx -y mnemos-capture@latest setup-hooks --key YOUR_KEY --vault
+```
+
+Before every `Edit`, `Write`, or `MultiEdit` tool call, Mnemos scans your vault for captures scoring ≥ 0.7 relevance to the file you're about to touch. Each capture is surfaced at most once per session.
+
+Opt-in only — not installed by default because it fires on every file edit.
+
+### Compatibility
+
+| Surface | Hook fires |
+|---|---|
+| Claude Code CLI, VS Code / JetBrains extensions, desktop app | Yes |
+| Claude Code on the web | No — `~/.claude/settings.json` is local only |
+| Cursor / other MCP clients | No — distinct hook systems |
+
+MCP tools work everywhere. For unsupported surfaces, add to `CLAUDE.md`:
+
+> At session start, call `list_inbox` to surface pending captures.
 
 
 ## MCP tools
 
-Mnemos exposes 7 tools via MCP, organized by what you're doing:
+Mnemos exposes 15 tools via MCP:
 
 ### Capture
 
 | Tool | What it does |
 |------|-------------|
-| `capture` | Extracts insight from any pasted content and commits a structured Markdown file to your repo. This is the entry point — everything starts here. |
+| `capture` | Extracts insight from any pasted content. Auto-detects source type, flags low-confidence input, auto-links to related captures. |
 
 ### Discover
 
 | Tool | What it does |
 |------|-------------|
-| `list_inbox` | Shows your unprocessed captures with summaries — title, type, tags, and core idea. Up to 10 at a time. Use this to see what's waiting for your review. |
-| `search_captures` | Searches your knowledge base by keyword or tag. Finds relevant captures across inbox, applied, and archived — so your agent can pull the right knowledge when it's needed. |
-| `read_capture` | Reads the full Markdown of any capture. Use this to see the complete insight, takeaways, and context before deciding what to do with it. |
+| `list_inbox` | Unprocessed captures with summaries — title, type, tags, core idea. |
+| `search_captures` | Keyword + tag search across inbox, applied, and archived. |
+| `read_capture` | Full Markdown of any capture. |
+| `recall` | Semantic search — describe your task, get the most relevant captures back. More powerful than keyword search. |
+
+### Apply
+
+| Tool | What it does |
+|------|-------------|
+| `apply_capture` | Moves inbox → applied. Records how and where knowledge was used, which plan drove it, and what changed. Triggers rule re-synthesis. |
+| `archive_capture` | Moves inbox → archived. Reviewed but not actionable now. |
+| `delete_capture` | Permanently removes a capture and its index entry. |
+| `apply_to_context` | Paste task + stack + code snippet → get concrete, file-level suggestions for applying your captured knowledge. |
+
+### Plan
+
+| Tool | What it does |
+|------|-------------|
+| `briefing` | Session-start briefing: ranked suggestions with `applyNow` flags, relevant rules, and a `generate_plan` prompt. Requires `project_context`. |
+| `generate_plan` | Reads selected captures + optional codebase files → structured Markdown plan with Codebase Mapping table, effort tiers per step, and Verification Checklist. Saved to `plans/`. |
+| `list_plans` | Lists saved plans, or reads a specific plan in full. |
 
-### Manage
+### Synthesize
 
 | Tool | What it does |
 |------|-------------|
-| `apply_capture` | Moves a capture from inbox to applied. Marks it as used — you can add a note about where you applied it (e.g., "Added as a rule in CLAUDE.md"). |
-| `archive_capture` | Moves a capture from inbox to archived. It's been reviewed but isn't actionable right now. Stays searchable, out of your inbox. |
-| `delete_capture` | Permanently removes a capture and its index entry. For mistakes or captures that aren't useful. |
+| `synthesize` | Distills captures on a tag into actionable rules. Updates `RULES.md`. |
+| `get_rules` | Returns synthesized rules — filtered by tag or all. Use to populate `CLAUDE.md` or a system prompt. |
 
-The web UI and MCP use the same pipeline. The web UI is for capturing on the go. MCP is for your agents — they retrieve and manage captures without you touching the browser.
+### Curate
+
+| Tool | What it does |
+|------|-------------|
+| `curate` | Validates inbox captures: HEAD-checks URLs (404/410 → stale), flags low-confidence extractions. Optional `auto_archive`. Batch cap: 20 files. |
+| `vault_scan` | Scans the full vault for captures relevant to your current activity (score ≥ 0.7). Used by the vault hook. |
+
+
+## CLI
+
+```
+mnemos-capture                                              Open hosted app
+mnemos-capture serve-mcp --key KEY                         Run local MCP proxy (auto-installs hook)
+mnemos-capture setup-hooks --key KEY [--briefing] [--vault] Install session hooks
+mnemos-capture inbox-check --key KEY [--briefing]          Debug what the hook runs
+mnemos-capture vault-check --key KEY                       Debug what the vault hook runs
+mnemos-capture help                                        Show help
+```
+
+All commands run via `npx -y mnemos-capture@latest <subcommand>`. `@latest` forces npm to resolve against the registry on every invocation.
 
 
 ## Mobile
 
-Open Mnemos in your phone's browser, tap **Share → Add to Home Screen**. It runs full-screen like a native app.
+Open Mnemos in your phone's browser → **Share → Add to Home Screen**. Runs full-screen like a native app. Capture while reading — your agents have it by the time you sit down to work.
 
-Capture on the go — reading an article on your phone at lunch? Capture it. Your agents have it by the time you sit down to work.
 
 ## Your data, your storage
 
 Your knowledge lives in a GitHub repo you own. Plain Markdown files, version-controlled, portable.
 
-- **No lock-in** — clone it, search it, move it, delete Mnemos tomorrow and your repo stays exactly where it is
+- **No lock-in** — clone it, move it, delete Mnemos and your repo stays exactly where it is
 - **No proprietary format** — every capture is a readable `.md` file
-- **No training on your data** — Mnemos never reads your captures for any purpose other than serving them back to you and your agents
+- **No training on your data** — Mnemos never reads your captures for any purpose other than serving them back to you
 - **Any tool can access it** — anything that reads Git or speaks MCP works with your knowledge base
+- **BYOK** — your provider, your key, your cost
 
 
 ## Cost
 
-Mnemos uses your own Anthropic API key (BYOK). You bring your key, Mnemos never charges you for API calls.
+Mnemos is BYOK — you bring your own API key, Mnemos never charges you for inference.
 
-Extraction runs on **Claude Haiku 4.5** with prompt caching and input truncation, optimized for minimal token usage:
+Extraction runs on a fast, low-cost model (Claude Haiku 4.5 by default) with prompt caching and input truncation:
 
 | Usage | Estimated monthly cost |
 |-------|----------------------|
@@ -240,28 +321,29 @@ Extraction runs on **Claude Haiku 4.5** with prompt caching and input truncation
 | 100 captures/month | ~$0.30 |
 | 200 captures/month | ~$0.60 |
 
-Less than $1/month for heavy use.
+Briefing and plan generation use your configured model and only run when you explicitly invoke them.
 
 
 ## Tech stack
 
-Next.js · TypeScript · Claude Haiku 4.5 · Anthropic SDK · GitHub OAuth · Vercel Postgres · GitHub Content API · MCP protocol · Tailwind CSS
+Next.js · TypeScript · Vercel Postgres · GitHub OAuth · GitHub Content API · MCP protocol · Anthropic SDK · Tailwind CSS · Vitest
+
 
 ## Roadmap
 
-- Chrome extension for one-click capture from anywhere in the browser
-- URL auto-fetch — paste a link, Mnemos fetches and extracts
-- Multi-provider support (OpenAI, Google — schema is ready)
+- **`mnemos kos`** — CLI orchestrator: creates isolated git worktree, launches your configured AI assistant with the plan as its contract, runs the Verification Checklist, reports the branch
+- **Provider abstraction** — bring your OpenAI, Google, or any OpenAI-compatible key; Mnemos routes accordingly
+- **Chrome extension** — one-click capture from anywhere in the browser
 - Voice memo capture
 
 
 ## Built by
 
-[Sofía Padrón Valdez](https://github.com/Soph20) — builder, AI systems architect. 
+[Sofía Padrón Valdez](https://github.com/Soph20) — builder, AI systems architect.
+
 
 ## Citation
 
-If you use this repository in your agentic workflows, please consider citing as follows:
 ```
 @misc{2026mnemos,
     title        = {Mnemos: A Knowledge Pipeline for AI Agents},

package/dist/cli/config.js

@@ -0,0 +1,70 @@
+/**
+ * Mnemos CLI config — stores which AI assistant kos should drive, and an
+ * optional API key, in ~/.mnemos/config.json. Provider/agent-agnostic: the
+ * user tells Mnemos the exact command to launch their assistant.
+ */
+import { homedir } from "os";
+import { join } from "path";
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
+const CONFIG_DIR = join(homedir(), ".mnemos");
+const CONFIG_PATH = join(CONFIG_DIR, "config.json");
+const ALLOWED_FIELDS = ["agent", "key"];
+export function readConfig() {
+    if (!existsSync(CONFIG_PATH))
+        return {};
+    try {
+        return JSON.parse(readFileSync(CONFIG_PATH, "utf-8"));
+    }
+    catch {
+        return {};
+    }
+}
+export function writeConfig(cfg) {
+    if (!existsSync(CONFIG_DIR))
+        mkdirSync(CONFIG_DIR, { recursive: true });
+    writeFileSync(CONFIG_PATH, JSON.stringify(cfg, null, 2) + "\n");
+}
+export function setConfigField(field, value) {
+    if (!ALLOWED_FIELDS.includes(field)) {
+        throw new Error(`Unknown config field: ${field}. Allowed: ${ALLOWED_FIELDS.join(", ")}`);
+    }
+    const cfg = readConfig();
+    cfg[field] = value;
+    writeConfig(cfg);
+}
+/** Route `mnemos config <set|get> ...`. */
+export function runConfigCommand(args) {
+    const action = args[0];
+    if (action === "set") {
+        const field = args[1];
+        const value = args.slice(2).join(" ");
+        if (!field || !value) {
+            console.error('Usage: mnemos config set <field> <value>');
+            console.error('  e.g. mnemos config set agent "claude -p"');
+            process.exit(1);
+        }
+        try {
+            setConfigField(field, value);
+            console.log(`Set ${field} = ${value}`);
+            console.log(`Saved to ${CONFIG_PATH}`);
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+        return;
+    }
+    if (action === "get") {
+        const cfg = readConfig();
+        const field = args[1];
+        if (field) {
+            console.log(cfg[field] ?? "(not set)");
+        }
+        else {
+            console.log(JSON.stringify(cfg, null, 2));
+        }
+        return;
+    }
+    console.error("Usage: mnemos config set|get <field> [value]");
+    process.exit(1);
+}

package/dist/cli/hooks.js

@@ -1,4 +1,4 @@
-import { homedir } from "os";
+import { homedir, tmpdir } from "os";
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
 import { join } from "path";
 import { execSync } from "child_process";
@@ -9,6 +9,9 @@ const CLAUDE_SETTINGS_PATH = join(homedir(), ".claude", "settings.json");
 function isMnemosHook(cmd) {
     return cmd.includes("mnemos-capture") && cmd.includes("inbox-check");
 }
+function isMnemosPreToolHook(cmd) {
+    return cmd.includes("mnemos-capture") && cmd.includes("vault-check");
+}
 function readSettings() {
     if (!existsSync(CLAUDE_SETTINGS_PATH))
         return {};
@@ -25,6 +28,47 @@ function writeSettings(settings) {
         mkdirSync(dir, { recursive: true });
     writeFileSync(CLAUDE_SETTINGS_PATH, JSON.stringify(settings, null, 2) + "\n");
 }
+// ── Session state for vault deduplication ──
+function sessionStateFile() {
+    const sessionId = process.env["CLAUDE_SESSION_ID"] ?? new Date().toISOString().split("T")[0] ?? "default";
+    return join(tmpdir(), `mnemos-vault-${sessionId}.json`);
+}
+function readSessionSurfaced() {
+    try {
+        const file = sessionStateFile();
+        if (!existsSync(file))
+            return [];
+        return JSON.parse(readFileSync(file, "utf-8"));
+    }
+    catch {
+        return [];
+    }
+}
+function appendSessionSurfaced(filenames) {
+    try {
+        const file = sessionStateFile();
+        const existing = readSessionSurfaced();
+        const updated = [...new Set([...existing, ...filenames])];
+        writeFileSync(file, JSON.stringify(updated));
+    }
+    catch {
+        // best-effort
+    }
+}
+// ── Stdin reader for hook context ──
+async function readStdin() {
+    return new Promise((resolve) => {
+        if (process.stdin.isTTY) {
+            resolve("");
+            return;
+        }
+        let data = "";
+        process.stdin.setEncoding("utf-8");
+        process.stdin.on("data", (chunk) => { data += chunk; });
+        process.stdin.on("end", () => resolve(data));
+        setTimeout(() => resolve(data), 2000);
+    });
+}
 export function setupHooks(apiKey, opts = {}) {
     const settings = readSettings();
     const hooks = settings.hooks ?? {};
@@ -73,6 +117,43 @@ export function setupHooks(apiKey, opts = {}) {
             console.log("At the start of each Claude Code session you'll see your inbox count.");
         }
     }
+    if (opts.vault) {
+        setupPreToolHook(apiKey, { silent: opts.silent, skipIfExists: opts.skipIfExists });
+    }
+}
+export function setupPreToolHook(apiKey, opts = {}) {
+    const settings = readSettings();
+    const hooks = settings.hooks ?? {};
+    const preToolCall = hooks.PreToolCall ?? [];
+    let existingCmd = null;
+    for (const group of preToolCall) {
+        for (const h of group.hooks ?? []) {
+            if (typeof h.command === "string" && isMnemosPreToolHook(h.command)) {
+                existingCmd = h.command;
+                break;
+            }
+        }
+        if (existingCmd)
+            break;
+    }
+    if (existingCmd && opts.skipIfExists) {
+        if (existingCmd.includes("mnemos-capture@latest"))
+            return;
+    }
+    const command = `npx -y mnemos-capture@latest vault-check --key ${apiKey}`;
+    const filtered = preToolCall
+        .map((group) => ({
+        ...group,
+        hooks: (group.hooks ?? []).filter((h) => !(typeof h.command === "string" && isMnemosPreToolHook(h.command))),
+    }))
+        .filter((group) => (group.hooks ?? []).length > 0);
+    filtered.push({ hooks: [{ type: "command", command }] });
+    settings.hooks = { ...hooks, PreToolCall: filtered };
+    writeSettings(settings);
+    if (!opts.silent) {
+        console.log("Mnemos vault hook installed (PreToolCall).");
+        console.log("Your knowledge vault will surface relevant captures as you edit files.");
+    }
 }
 function run(cmd) {
     return execSync(cmd, { timeout: 2000, stdio: ["pipe", "pipe", "pipe"] }).toString().trim();
@@ -116,7 +197,7 @@ function detectProjectContext() {
     catch { }
     return parts.length > 0 ? parts.join("\n\n") : "current project";
 }
-async function callMcp(apiKey, toolName, toolArgs) {
+export async function callMcp(apiKey, toolName, toolArgs, timeoutMs = 15000) {
     const res = await fetch(HOSTED_URL, {
         method: "POST",
         headers: {
@@ -129,20 +210,78 @@ async function callMcp(apiKey, toolName, toolArgs) {
             params: { name: toolName, arguments: toolArgs },
             id: 1,
         }),
-        signal: AbortSignal.timeout(15000),
+        signal: AbortSignal.timeout(timeoutMs),
     });
     if (!res.ok)
         return null;
     const data = (await res.json());
     return data.result?.content?.[0]?.text ?? null;
 }
+export async function vaultCheck(apiKey) {
+    try {
+        const inputJson = await readStdin();
+        if (!inputJson.trim())
+            return;
+        let hookData;
+        try {
+            hookData = JSON.parse(inputJson);
+        }
+        catch {
+            return;
+        }
+        // Only act on file-editing tool calls
+        const editingTools = ["Edit", "Write", "MultiEdit"];
+        if (!hookData.tool_name || !editingTools.includes(hookData.tool_name))
+            return;
+        const filePath = hookData.tool_input?.["file_path"] ??
+            hookData.tool_input?.["path"];
+        if (!filePath)
+            return;
+        const projectCtx = detectProjectContext();
+        const activityContext = `Editing file: ${filePath}\nProject context:\n${projectCtx}`;
+        const sessionSurfaced = readSessionSurfaced();
+        const text = await callMcp(apiKey, "vault_scan", {
+            activity_context: activityContext,
+            session_surfaced: sessionSurfaced,
+        }, 8000);
+        if (!text?.trim())
+            return;
+        // Track surfaced filenames to avoid repetition within the session
+        const filenameMatches = text.match(/(?:inbox|applied|archived)\/[\w-]+\.md/g) ?? [];
+        if (filenameMatches.length > 0)
+            appendSessionSurfaced(filenameMatches);
+        process.stdout.write(text.trim() + "\n");
+    }
+    catch {
+        // Silent fail — never interrupt a tool call
+    }
+}
 export async function inboxCheck(apiKey, opts = {}) {
     try {
         if (opts.briefing) {
             const projectContext = detectProjectContext();
             const text = await callMcp(apiKey, "briefing", { project_context: projectContext });
-            if (text?.trim())
-                process.stdout.write(text.trim() + "\n");
+            if (!text?.trim())
+                return;
+            const jsonMatch = text.match(/```json\n([\s\S]*?)\n```/);
+            let applyNow = [];
+            if (jsonMatch?.[1]) {
+                try {
+                    const all = JSON.parse(jsonMatch[1]);
+                    applyNow = all.filter((s) => s.applyNow);
+                }
+                catch {
+                    applyNow = [];
+                }
+            }
+            // Strip the JSON block — display only the Markdown narrative
+            const displayText = text.replace(/```json[\s\S]*?```\n?/, "").trim();
+            process.stdout.write(displayText + "\n");
+            if (applyNow.length > 0) {
+                const filenames = applyNow.map((s) => `'${s.filename}'`).join(", ");
+                process.stdout.write(`\n---\nMnemos: ${applyNow.length} insight${applyNow.length === 1 ? "" : "s"} ready to apply now.\n` +
+                    `Run generate_plan with selected_captures: [${filenames}] to get a full implementation plan.\n`);
+            }
             return;
         }
         // Default: fast count via list_inbox (no LLM call)

package/dist/cli/index.js

@@ -17,10 +17,10 @@ async function main() {
         const keyIdx = args.indexOf("--key");
         const apiKey = keyIdx !== -1 ? args[keyIdx + 1] : undefined;
         if (!apiKey) {
-            console.error("Usage: npx mnemos-capture setup-hooks --key YOUR_API_KEY [--briefing]");
+            console.error("Usage: npx mnemos-capture setup-hooks --key YOUR_API_KEY [--briefing] [--vault]");
             process.exit(1);
         }
-        setupHooks(apiKey, { briefing: args.includes("--briefing") });
+        setupHooks(apiKey, { briefing: args.includes("--briefing"), vault: args.includes("--vault") });
         return;
     }
     if (command === "inbox-check") {
@@ -32,6 +32,34 @@ async function main() {
         await inboxCheck(apiKey, { briefing: args.includes("--briefing") });
         return;
     }
+    if (command === "vault-check") {
+        const { vaultCheck } = await import("./hooks.js");
+        const keyIdx = args.indexOf("--key");
+        const apiKey = keyIdx !== -1 ? args[keyIdx + 1] : undefined;
+        if (!apiKey)
+            process.exit(0); // silent fail in hook context
+        await vaultCheck(apiKey);
+        return;
+    }
+    if (command === "config") {
+        const { runConfigCommand } = await import("./config.js");
+        runConfigCommand(args.slice(1));
+        return;
+    }
+    if (command === "kos") {
+        const { kos } = await import("./kos.js");
+        const { readConfig } = await import("./config.js");
+        const keyIdx = args.indexOf("--key");
+        const apiKey = keyIdx !== -1 ? args[keyIdx + 1] : readConfig().key;
+        if (!apiKey) {
+            console.error("No API key. Pass --key YOUR_KEY or store it: mnemos config set key YOUR_KEY");
+            process.exit(1);
+        }
+        const planIdx = args.indexOf("--plan");
+        const plan = planIdx !== -1 ? args[planIdx + 1] : undefined;
+        await kos(apiKey, { plan });
+        return;
+    }
     // Default: open the hosted app
     console.log("");
     console.log("  Mnemos — Knowledge capture for agentic workflows\n");
@@ -52,11 +80,30 @@ function printHelp() {
   Mnemos — Knowledge capture for agentic workflows
 
   Usage:
-    npx mnemos-capture                                   Open Mnemos in your browser
-    npx mnemos-capture serve-mcp --key KEY               Start the MCP server for Claude Code
-    npx mnemos-capture setup-hooks --key KEY             Install inbox count hook (fast)
-    npx mnemos-capture setup-hooks --key KEY --briefing  Install full briefing hook (uses LLM)
-    npx mnemos-capture help                              Show this help
+    npx mnemos-capture                                         Open Mnemos in your browser
+    npx mnemos-capture serve-mcp --key KEY                     Start the MCP server for Claude Code
+    npx mnemos-capture setup-hooks --key KEY                   Install inbox count hook (fast)
+    npx mnemos-capture setup-hooks --key KEY --briefing        Install full briefing hook (uses LLM)
+    npx mnemos-capture setup-hooks --key KEY --vault           Install vault hook (PreToolCall)
+    npx mnemos-capture setup-hooks --key KEY --briefing --vault  Install both hooks
+    npx mnemos-capture config set agent "claude -p"            Set which AI assistant kos drives
+    npx mnemos-capture kos --key KEY [--plan FILE]             Implement a plan in an isolated worktree
+    npx mnemos-capture help                                    Show this help
+
+  MCP tools (via your AI assistant):
+    briefing          — Session-start briefing with ranked insights to apply
+    generate_plan     — Turn selected captures into a full implementation plan
+    list_plans        — List or read saved implementation plans
+    vault_scan        — Scan all captures for relevance to current activity
+    curate            — Validate URLs and flag stale captures
+
+  kos — implement plans with your own AI assistant (model-agnostic):
+    1. Tell Mnemos which assistant to drive (once):
+         mnemos config set agent "claude -p"      # or "codex exec", "aider --yes --message"
+    2. Generate a plan via the generate_plan MCP tool.
+    3. Run: mnemos kos --key YOUR_KEY
+       kos creates an isolated git worktree, hands the plan to your assistant,
+       and reports the branch + the plan's Verification Checklist when done.
 
   Get started:
     1. Run: npx mnemos-capture
@@ -74,6 +121,9 @@ function printHelp() {
   The hook is installed automatically when you start the MCP server.
   To upgrade to a full project briefing at session start:
     npx mnemos-capture setup-hooks --key YOUR_API_KEY --briefing
+
+  To enable the vault (surfaces captures as you edit files — opt-in):
+    npx mnemos-capture setup-hooks --key YOUR_API_KEY --vault
   `);
 }
 main().catch((err) => {

package/dist/cli/kos.js

@@ -0,0 +1,123 @@
+/**
+ * kos — Mnemos' Knowledge Operations orchestrator.
+ *
+ * Drives whatever AI assistant the user configured (`mnemos config set agent ...`)
+ * to implement a generated plan in an isolated git worktree. Mnemos owns the
+ * harness-independent parts: fetching the plan, the worktree, and reporting the
+ * Verification Checklist. The assistant is a black box — model-agnostic by design.
+ */
+import { tmpdir } from "os";
+import { join } from "path";
+import { writeFileSync, existsSync, appendFileSync, readFileSync } from "fs";
+import { execSync } from "child_process";
+import { callMcp } from "./hooks.js";
+import { readConfig } from "./config.js";
+// ── Pure helpers (exported for testing) ──
+/** Extract `**filename.md**` plan names from a list_plans response. */
+export function parsePlanFilenames(listText) {
+    const matches = listText.match(/\*\*([^*]+\.md)\*\*/g) ?? [];
+    return matches.map((m) => m.replace(/\*\*/g, ""));
+}
+/** Pick the newest plan. Filenames are date-prefixed (YYYY-MM-DD-...), so lexical desc = newest. */
+export function latestPlanFilename(listText) {
+    const names = parsePlanFilenames(listText);
+    if (names.length === 0)
+        return null;
+    return [...names].sort((a, b) => b.localeCompare(a))[0] ?? null;
+}
+/** Pull the Verification Checklist items out of a plan's Markdown. */
+export function parseChecklist(planText) {
+    const section = planText.match(/##\s*Verification Checklist\s*\n([\s\S]*?)(?=\n##\s|$)/i);
+    if (!section?.[1])
+        return [];
+    return section[1]
+        .split("\n")
+        .map((l) => l.trim())
+        .filter((l) => /^- \[[ x]\]/i.test(l))
+        .map((l) => l.replace(/^- \[[ x]\]\s*/i, ""));
+}
+/** Build a unique, sortable branch name for a kos run. */
+export function buildKosBranch(now = new Date()) {
+    const stamp = now.toISOString().replace(/[:.]/g, "-").replace("T", "-").slice(0, 19);
+    return `mnemos/kos-${stamp}`;
+}
+/** The instruction handed to the assistant. The plan file is the real contract. */
+export const KOS_PROMPT = "Implement the plan in MNEMOS_PLAN.md in this repository. " +
+    "Follow the Codebase Mapping table exactly — change only the files it lists. " +
+    "For each step apply the thinking effort named in its Effort column " +
+    "(low = quick/mechanical, medium = careful, high = deep reasoning). " +
+    "When finished, make sure every item in the Verification Checklist is satisfied.";
+// ── Orchestrator ──
+function run(cmd, cwd) {
+    return execSync(cmd, { cwd, stdio: ["pipe", "pipe", "pipe"] }).toString().trim();
+}
+export async function kos(apiKey, opts = {}) {
+    const cfg = readConfig();
+    if (!cfg.agent) {
+        console.error("No agent configured. Tell Mnemos which AI assistant to drive:\n");
+        console.error('  mnemos config set agent "claude -p"               # Claude Code');
+        console.error('  mnemos config set agent "codex exec"              # Codex');
+        console.error('  mnemos config set agent "aider --yes --message"   # Aider');
+        process.exit(1);
+    }
+    // 1. Resolve the plan — explicit filename, or the newest saved plan
+    const planFile = opts.plan ?? latestPlanFilename((await callMcp(apiKey, "list_plans", {}, 15000)) ?? "");
+    if (!planFile) {
+        console.error("No plans found. Generate one first with the generate_plan MCP tool.");
+        process.exit(1);
+    }
+    const planText = await callMcp(apiKey, "list_plans", { filename: planFile }, 15000);
+    if (!planText || !planText.trim()) {
+        console.error(`Could not read plan: ${planFile}`);
+        process.exit(1);
+    }
+    // 2. Must be inside a git repo
+    let repoRoot;
+    try {
+        repoRoot = run("git rev-parse --show-toplevel");
+    }
+    catch {
+        console.error("mnemos kos must be run inside a git repository.");
+        process.exit(1);
+        return;
+    }
+    // 3. Isolated worktree on a fresh branch
+    const branch = buildKosBranch();
+    const worktreePath = join(tmpdir(), branch.replace(/\//g, "-"));
+    console.log(`Creating isolated worktree on branch ${branch}...`);
+    run(`git worktree add -b ${branch} "${worktreePath}"`, repoRoot);
+    // 4. Drop the plan in and keep git from tracking it (local exclude, not committed)
+    writeFileSync(join(worktreePath, "MNEMOS_PLAN.md"), planText);
+    try {
+        const excludePath = join(repoRoot, ".git", "info", "exclude");
+        if (existsSync(excludePath)) {
+            const current = readFileSync(excludePath, "utf-8");
+            if (!current.includes("MNEMOS_PLAN.md"))
+                appendFileSync(excludePath, "\nMNEMOS_PLAN.md\n");
+        }
+    }
+    catch {
+        // best-effort
+    }
+    // 5. Hand off to the user's assistant, running inside the worktree
+    console.log(`Launching: ${cfg.agent}\n`);
+    try {
+        execSync(`${cfg.agent} ${JSON.stringify(KOS_PROMPT)}`, { cwd: worktreePath, stdio: "inherit" });
+    }
+    catch {
+        console.error("\nThe agent exited with an error. The worktree is preserved for inspection.");
+    }
+    // 6. Report — branch + the plan's own checklist as the review gate
+    const checklist = parseChecklist(planText);
+    console.log(`\n${"─".repeat(60)}`);
+    console.log(`kos finished. Plan: ${planFile}`);
+    console.log(`Branch:   ${branch}`);
+    console.log(`Worktree: ${worktreePath}`);
+    if (checklist.length > 0) {
+        console.log(`\nVerify before merging:`);
+        for (const item of checklist)
+            console.log(`  [ ] ${item}`);
+    }
+    console.log(`\nReview the branch, then merge. Clean up the worktree with:`);
+    console.log(`  git worktree remove "${worktreePath}"`);
+}

package/dist/cli/mcp-server.js

@@ -2,8 +2,7 @@
 // Used by Claude Code: claude mcp add mnemos -- npx mnemos-capture serve-mcp --key <api-key>
 const HOSTED_URL = "https://mnemos-capture.vercel.app/api/mcp";
 function sendMessage(msg) {
-    const json = JSON.stringify(msg);
-    process.stdout.write(`Content-Length: ${Buffer.byteLength(json)}\r\n\r\n${json}`);
+    process.stdout.write(`${JSON.stringify(msg)}\n`);
 }
 async function proxyToHosted(apiKey, msg) {
     try {
@@ -62,31 +61,21 @@ export async function serveMcp() {
     process.stdin.setEncoding("utf-8");
     process.stdin.on("data", (chunk) => {
         buffer += chunk;
-        while (true) {
-            const headerEnd = buffer.indexOf("\r\n\r\n");
-            if (headerEnd === -1)
-                break;
-            const header = buffer.slice(0, headerEnd);
-            const match = header.match(/Content-Length:\s*(\d+)/i);
-            if (!match) {
-                buffer = buffer.slice(headerEnd + 4);
+        let newlineIdx;
+        while ((newlineIdx = buffer.indexOf("\n")) !== -1) {
+            const line = buffer.slice(0, newlineIdx).trim();
+            buffer = buffer.slice(newlineIdx + 1);
+            if (!line)
                 continue;
-            }
-            const contentLength = parseInt(match[1], 10);
-            const bodyStart = headerEnd + 4;
-            if (buffer.length < bodyStart + contentLength)
-                break;
-            const body = buffer.slice(bodyStart, bodyStart + contentLength);
-            buffer = buffer.slice(bodyStart + contentLength);
             try {
-                const msg = JSON.parse(body);
+                const msg = JSON.parse(line);
                 // Handle notifications/initialized locally (no response needed)
                 if (msg.method === "notifications/initialized")
                     continue;
                 void proxyToHosted(apiKey, msg);
             }
             catch {
-                process.stderr.write(`Failed to parse: ${body}\n`);
+                process.stderr.write(`Failed to parse: ${line}\n`);
             }
         }
     });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mnemos-capture",
-  "version": "1.1.0",
-  "description": "Zero-friction knowledge capture for agentic workflows. Paste anything → Claude extracts insights → auto-commits to your knowledge repo → your Claude Code workflow picks it up.",
+  "version": "1.2.1",
+  "description": "Capture anything. Your agents apply it. A knowledge pipeline that ingests the outside world and makes it directly actionable by any AI agent over MCP.",
   "type": "module",
   "bin": {
     "mnemos-capture": "./dist/cli/index.js"
@@ -11,7 +11,10 @@
     "build": "next build",
     "start": "next start",
     "build:cli": "tsc -p cli/tsconfig.json",
-    "prepublishOnly": "npm run build:cli"
+    "prepublishOnly": "npm run build:cli",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:e2e": "playwright test"
   },
   "keywords": [
     "ai",
@@ -45,13 +48,15 @@
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
+    "@playwright/test": "^1.61.1",
     "@types/node": "^20",
     "@types/react": "^19",
     "@types/react-dom": "^19",
     "autoprefixer": "^10.4.21",
     "postcss": "^8.5.3",
     "tailwindcss": "^3.4.17",
-    "typescript": "^5"
+    "typescript": "^5",
+    "vitest": "^4.1.8"
   },
   "engines": {
     "node": ">=18"