mnemos-capture 1.0.6 → 1.2.0

package/README.md

@@ -4,133 +4,344 @@
 
 <h1 align="center">Mnemos</h1>
 
-<p align="center"><strong>Capture knowledge. Apply it through your agents.</strong></p>
+<p align="center">
+  <img src="https://img.shields.io/npm/v/mnemos-capture" alt="npm" />
+  <img src="https://img.shields.io/badge/license-MIT-blue" alt="License" />
+  <img src="https://img.shields.io/badge/MCP-compatible-green" alt="MCP" />
+</p>
+
+<p align="center"><strong>Capture anything. Your agents apply it.</strong></p>
+
+<p align="center">A knowledge pipeline that ingests the outside world and makes it directly actionable by any AI agent — over MCP.</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. **Your AI agent finally knows what you've been reading.**
+
+Mnemos is the pipeline between the two. Capture any insight once — Mnemos extracts it, stores it as plain Markdown in your own GitHub repo, and serves it to your agent over MCP. Then it goes further: at session start it briefs your agent on what matters right now, turns insights into implementation plans, and hands them to whatever assistant you run — Claude Code, Codex, Cursor, Gemini, anything MCP-compatible.
+
+It's not a second brain, a vault, or a note-taking app — those store knowledge for *you* to read later. Mnemos makes knowledge your **agent acts on now**.
+
+
+## Get started
+
+### 1. Sign up (30 seconds)
+
+Go to **[mnemos-capture.vercel.app](https://mnemos-capture.vercel.app)** → **Sign in with GitHub**.
 
-Mnemos is a knowledge pipeline for builders who work with AI agents. You learn something — an article, a thread, a transcript, your own notes, an idea on the go — and instead of bookmarking it or letting it rot in a tab, you paste it into Mnemos. An LLM extracts the core insight, tags it by topic, and commits it to a GitHub repo you own.
+During setup, Mnemos will:
 
-That repo becomes your personal knowledge base. Your AI agents — Claude Code, Codex, or any MCP-compatible tool — pull from it directly. The knowledge you captured on your phone during lunch is available to your coding agent by the time you sit down to work.
+- Create a knowledge repo in your GitHub account — plain Markdown files, no proprietary format
+- 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
 
-**This is not a note-taking app.** It's a bridge between what you learn and what your agents do.
+No config files. No repos to clone. No CLI setup required.
 
-## Why Mnemos exists
+### 2. Connect to your AI assistant
 
-Most knowledge tools stop at "save it." Mnemos closes the loop:
+When you finish onboarding, Mnemos generates a personal **MCP API key** — copy it.
 
-1. **You capture** — paste anything: articles, threads, transcripts, meeting notes, ideas, voice memo transcripts, book highlights
-2. **AI extracts** — an LLM pulls the actual insight (not a summary), tags it by topic, and connects it to what you're building right now
-3. **Your agents apply it** — Claude Code, Codex, or any agentic tool reads your knowledge repo via MCP or Git and uses it in real workflows
+**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
+npx -y mnemos-capture@latest serve-mcp --key <your-mcp-key>
+```
+
+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.
+
+### 3. Capture something
+
+Open the app on any device — phone, tablet, or desktop. Paste any content and hit **Capture**. Or capture directly from your agent:
+
+```
+capture "The Mom Test — don't ask if your idea is good, ask about their life."
+```
+
+That's it. Your knowledge is now indexed and available to every agent session.
 
-Every capture includes an **"Applied to"** field — a concrete sentence linking what you learned to what you're building. This is the difference between a saved-for-later graveyard and a knowledge system that compounds.
 
 ## How it works
 
 ```mermaid
-flowchart LR
-    A["Read an article,\nhear a podcast,\nhave an idea"] -->|paste| B["Mnemos\n(web / mobile)"]
-    B -->|extract| C["Core idea\nTakeaways\nApplied to"]
-    C -->|commit| D["Your GitHub repo\n(Markdown)"]
-    D -->|MCP| E["Claude Code"]
-    D -->|Git read| F["Codex"]
-    D -->|API / Git| G["Your agents"]
+flowchart TD
+    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 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:#1a1a2e,stroke:#444,color:#fff
+    style G fill:#2d8a4e,stroke:#1e6b3a,color:#fff
 ```
 
-## What you can capture
+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.
 
-Mnemos handles any text-based input. Paste it, and the LLM figures out the format and extracts accordingly.
 
-- **Articles and blog posts** — the insight, not a summary
-- **Twitter/X threads** — the argument stitched together
-- **Podcast and meeting transcripts** — the signal, not the filler
-- **Your own notes and ideas** — raw thoughts turned into structured knowledge
-- **Book highlights and excerpts** — the quotes and frameworks worth keeping
-- **Newsletter and Substack posts** — the actionable takeaways
+## What you can feed it
 
-Coming soon: voice memos, URL auto-fetch, and browser extension for one-click capture.
+If it's text, Mnemos can extract insight from it. No manual tagging required.
 
-## Cost
+- **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
 
-Mnemos uses your own Anthropic API key (BYOK — you bring your own key, Mnemos never charges you).
 
-Extraction runs on **Claude Haiku 4.5** with prompt caching and input truncation, optimized for minimal token usage:
+## Example capture
 
-| Usage | Estimated monthly cost |
-|-------|----------------------|
-| 50 captures/month (casual) | ~$0.15 |
-| 100 captures/month (regular) | ~$0.30 |
-| 200 captures/month (heavy) | ~$0.60 |
+Paste a research post about error observability. This is what lands in your repo:
 
-Less than $1/month for heavy use. For comparison, the same workload on a larger model without optimization would cost 5-6x more.
+```markdown
+---
+date: 2026-06-05
+source: Error Context First — Observability for AI Systems
+url: https://example.com/error-context
+type: post
+source_type: url
+tags: observability, error-handling, ai-agents, debugging
+status: inbox
+lowConfidence: false
+---
 
-## Get started
+# Error Context First — Observability for AI Systems
 
-### 1. Sign up (30 seconds)
+## Core idea
+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.
 
-Go to **[mnemos-capture.vercel.app](https://mnemos-capture.vercel.app)** → **Sign in with GitHub**.
+## Key takeaways
+- 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
 
-During setup, Mnemos will:
+## Applied to
+Add handler-name prefixes to every catch block in your agent's tool pipeline.
+```
 
-- Create a knowledge repo in your GitHub account (you own it — just Markdown files in a repo under your name)
-- Ask for your Anthropic API key (your key, stored per-user — Mnemos never pays for your API calls)
-- Set a PIN so you can unlock the app quickly on mobile
+`source_type` is auto-detected (`url` / `note` / `paste`). `lowConfidence` flags short or ambiguous input for review before acting on it.
+
+
+## Knowledge lifecycle
+
+```
+  ┌─────────┐
+  │  Capture │
+  └────┬─────┘
+       ▼
+  ┌─────────┐     ┌──────────┐
+  │  Inbox   │────▶│  Applied  │   Insight used — plan executed, rule added, code changed
+  └────┬─────┘     └──────────┘
+       │
+       ├──────────▶┌──────────┐
+       │           │ Archived  │   Reviewed, not actionable right now
+       │           └──────────┘
+       │
+       └──────────▶┌──────────┐
+                   │ Deleted   │   Not useful, permanently removed
+                   └──────────┘
+```
+
+All captures are tracked in `INDEX.md` — a master table your agents search across your entire knowledge base. Generated plans land in `plans/`.
+
+
+## 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:
 
-No config files. No CLI setup. No repos to clone.
+```bash
+npx -y mnemos-capture@latest setup-hooks --key YOUR_KEY --briefing
+```
 
-### 2. Capture something
+At session start, Mnemos collects your project context — branch, recent commits, CLAUDE.md excerpt — and returns:
 
-Open the app on any device — phone, tablet, or desktop. Paste any content and hit **Capture**. That's it.
+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
 
-The result is auto-committed to your GitHub knowledge repo as a structured Markdown file.
+```
+3 insights to apply now:
 
-### 3. Connect to Claude Code (optional)
+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
 
-After signing up, you get an API key. This connects Mnemos to Claude Code so your agent can capture and search your knowledge without leaving the terminal.
+Run generate_plan with selected_captures: ["inbox/2026-06-05-error-context-first.md"]
+```
 
-Run this once:
+### Vault mode (PreToolCall hook)
+
+Surfaces relevant captures *before* you edit a file — not just at session start:
 
 ```bash
-claude mcp add mnemos -- npx mnemos-capture serve-mcp --key <your-api-key>
+npx -y mnemos-capture@latest setup-hooks --key YOUR_KEY --vault
 ```
 
-Now you can say things like:
+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 15 tools via MCP:
 
-- *"Capture this article about prompt caching"*
-- *"What's in my inbox?"*
-- *"Search my captures for evaluation frameworks"*
+### Capture
 
-**Under the hood:** `npx mnemos-capture serve-mcp` runs a lightweight local process that bridges Claude Code's stdio protocol to the Mnemos HTTP API. Your API key authenticates the requests. No data is stored locally — everything goes to your GitHub repo via the hosted app.
+| Tool | What it does |
+|------|-------------|
+| `capture` | Extracts insight from any pasted content. Auto-detects source type, flags low-confidence input, auto-links to related captures. |
 
-## Mobile access
+### Discover
 
-Mnemos is a PWA. On your phone, open the app URL in your browser → Share → **Add to Home Screen**. Native-app feel, instant capture from anywhere.
+| Tool | What it does |
+|------|-------------|
+| `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. |
+
+### Synthesize
+
+| Tool | What it does |
+|------|-------------|
+| `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. |
+
+### 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
+```
 
-## Why GitHub as storage?
+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 → **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.
+
+
+## Your data, your storage
+
+Your knowledge lives in a GitHub repo you own. Plain Markdown files, version-controlled, portable.
+
+- **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
+- **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 is BYOK — you bring your own API key, Mnemos never charges you for inference.
+
+Extraction runs on a fast, low-cost model (Claude Haiku 4.5 by default) with prompt caching and input truncation:
+
+| Usage | Estimated monthly cost |
+|-------|----------------------|
+| 50 captures/month | ~$0.15 |
+| 100 captures/month | ~$0.30 |
+| 200 captures/month | ~$0.60 |
+
+Briefing and plan generation use your configured model and only run when you explicitly invoke them.
 
-Your knowledge lives in a repo you own. No proprietary database, no vendor lock-in. It's version-controlled, portable, and readable as plain Markdown. Clone it, search it, back it up — it's just files. And because it's a standard Git repo, any MCP-compatible agent or tool can read from it directly.
 
 ## Tech stack
 
-Next.js · TypeScript (strict) · Anthropic SDK · GitHub OAuth · Vercel Postgres (Neon) · GitHub API · MCP protocol · Tailwind CSS
+Next.js · TypeScript · Vercel Postgres · GitHub OAuth · GitHub Content API · MCP protocol · Anthropic SDK · Tailwind CSS · Vitest
+
 
 ## Roadmap
 
-- [ ] Multi-provider support (OpenAI, Google — schema is ready)
-- [ ] Voice memo capture
-- [ ] URL auto-fetch (paste a link, Mnemos fetches the content)
-- [ ] Batch capture (multiple resources at once)
-- [ ] Browser extension for one-click capture
-- [ ] Full-text search across knowledge hub
-- [ ] Custom user-defined categories
-- [ ] Settings page (change API key, repo, regenerate MCP key)
-- [ ] Team knowledge hubs (shared captures)
+- **`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.
+
+
+## Citation
+
+```
+@misc{2026mnemos,
+    title        = {Mnemos: A Knowledge Pipeline for AI Agents},
+    author       = {Sofia Padron Valdez},
+    year         = 2026,
+    journal      = {GitHub repository},
+    publisher    = {GitHub},
+    howpublished = {\url{https://github.com/Soph20/mnemos-capture}}
+    }
+```
 
 ## License
 
-[MIT](LICENSE)
+[MIT License - see LICENSE file for details](./LICENSE)

package/dist/cli/__tests__/config.test.js

@@ -0,0 +1,49 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, rmSync, readFileSync, existsSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+describe("config", () => {
+    let tmpDir;
+    let configPath;
+    let origHome;
+    beforeEach(() => {
+        tmpDir = mkdtempSync(join(tmpdir(), "mnemos-config-test-"));
+        configPath = join(tmpDir, ".mnemos", "config.json");
+        origHome = process.env["HOME"];
+        process.env["HOME"] = tmpDir;
+        // Module-level CONFIG_DIR is computed from homedir() at import — reset cache
+        vi.resetModules();
+    });
+    afterEach(() => {
+        rmSync(tmpDir, { recursive: true, force: true });
+        process.env["HOME"] = origHome;
+    });
+    it("returns an empty object when no config exists", async () => {
+        const { readConfig } = await import("../config.js");
+        expect(readConfig()).toEqual({});
+    });
+    it("writes and reads back the agent field", async () => {
+        const { setConfigField, readConfig } = await import("../config.js");
+        setConfigField("agent", "claude -p");
+        expect(readConfig().agent).toBe("claude -p");
+        expect(existsSync(configPath)).toBe(true);
+    });
+    it("persists the agent command verbatim, including flags", async () => {
+        const { setConfigField } = await import("../config.js");
+        setConfigField("agent", "aider --yes --message");
+        const saved = JSON.parse(readFileSync(configPath, "utf-8"));
+        expect(saved.agent).toBe("aider --yes --message");
+    });
+    it("preserves other fields when updating one", async () => {
+        const { setConfigField, readConfig } = await import("../config.js");
+        setConfigField("key", "mnemos_abc123");
+        setConfigField("agent", "codex exec");
+        const cfg = readConfig();
+        expect(cfg.key).toBe("mnemos_abc123");
+        expect(cfg.agent).toBe("codex exec");
+    });
+    it("throws on an unknown config field", async () => {
+        const { setConfigField } = await import("../config.js");
+        expect(() => setConfigField("provider", "openai")).toThrow(/Unknown config field/);
+    });
+});