mnemos-capture 1.0.6 → 1.1.0

package/README.md

@@ -4,133 +4,275 @@
 
 <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>A knowledge pipeline for AI agents.<br />Capture anything — your agents retrieve and 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.
+
+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.
+
+
+## Get started
+
+### 1. Sign up (30 seconds)
+
+Go to **[mnemos-capture.vercel.app](https://mnemos-capture.vercel.app)** → **Sign in with GitHub**.
+
+During setup, Mnemos will:
 
-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.
+- 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
+- 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
 
-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.
+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.
+
+### 3. Connect to Claude Code
+
+After signing up, you get an MCP API key. Run this once on your machine:
+
+```bash
+claude mcp add mnemos -- npx -y mnemos-capture@latest serve-mcp --key <your-api-key>
+```
+
+Your agent confirms the connection and can immediately access your knowledge base.
+
+> `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.
+
+**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:
+
+```
+Mnemos: 3 captures in inbox — run list_inbox to review
+```
+
+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
+```
 
-**This is not a note-taking app.** It's a bridge between what you learn and what your agents do.
+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).
 
-## Why Mnemos exists
+**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.
 
-Most knowledge tools stop at "save it." Mnemos closes the loop:
+### 4. Connect to any MCP-compatible agent
 
-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
+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.
 
-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 / 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"]
 
     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:#1a1a2e,stroke:#444,color:#fff
-    style G fill:#1a1a2e,stroke:#444,color:#fff
+    style F fill:#2A62C6,stroke:#1a4a9e,color:#fff
+    style G fill:#2d8a4e,stroke:#1e6b3a,color:#fff
+    style H fill:#1a1a2e,stroke:#444,color:#fff
 ```
 
-## What you can capture
+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.
+
+### Example output
+
+Paste a research post about multi-agent systems. This is what gets committed to your repo:
+
+```markdown
+---
+date: 2026-04-01
+source: Why Multi-Agent Systems Outperform Single-Agent Loops
+url: https://example.com/multi-agent-systems
+type: post
+tags: multi-agent, orchestration, agent-design, ai-architecture
+status: inbox
+---
+
+# Why Multi-Agent Systems Outperform Single-Agent Loops
+
+## 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.
+
+## 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."
+
+## Applied to
+Evaluate your current single-agent workflows for tasks that could be decomposed
+into parallel subagent calls — prioritize anything with 3+ sequential steps.
+```
 
-Mnemos handles any text-based input. Paste it, and the LLM figures out the format and extracts accordingly.
+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.
 
-- **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
 
-Coming soon: voice memos, URL auto-fetch, and browser extension for one-click capture.
+## What you can feed it
 
-## Cost
+If it's text, Mnemos can extract insight from it. You don't need to categorize or tag anything yourself — that happens automatically.
 
-Mnemos uses your own Anthropic API key (BYOK — you bring your own key, Mnemos never charges you).
+- **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
 
-Extraction runs on **Claude Haiku 4.5** with prompt caching and input truncation, optimized for minimal token usage:
 
-| Usage | Estimated monthly cost |
-|-------|----------------------|
-| 50 captures/month (casual) | ~$0.15 |
-| 100 captures/month (regular) | ~$0.30 |
-| 200 captures/month (heavy) | ~$0.60 |
+## Knowledge lifecycle
 
-Less than $1/month for heavy use. For comparison, the same workload on a larger model without optimization would cost 5-6x more.
+Knowledge that sits unreviewed rots. Mnemos forces a decision: apply it, save it for later, or discard it.
 
-## Get started
+```
+  ┌─────────┐
+  │  Capture │
+  └────┬─────┘
+       ▼
+  ┌─────────┐     ┌──────────┐
+  │  Inbox   │────▶│  Applied  │   You used the insight in your workflow
+  └────┬─────┘     └──────────┘
+       │
+       ├──────────▶┌──────────┐
+       │           │ Archived  │   Reviewed, not actionable right now
+       │           └──────────┘
+       │
+       └──────────▶┌──────────┐
+                   │ Deleted   │   Not useful, permanently removed
+                   └──────────┘
+```
 
-### 1. Sign up (30 seconds)
+**How it works in practice:**
 
-Go to **[mnemos-capture.vercel.app](https://mnemos-capture.vercel.app)** → **Sign in with GitHub**.
+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.
 
-During setup, Mnemos will:
+All captures are tracked in `INDEX.md` — a master table your agents use to search across your entire knowledge base.
 
-- 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
 
-No config files. No CLI setup. No repos to clone.
+## MCP tools
 
-### 2. Capture something
+Mnemos exposes 7 tools via MCP, organized by what you're doing:
 
-Open the app on any device — phone, tablet, or desktop. Paste any content and hit **Capture**. That's it.
+### Capture
 
-The result is auto-committed to your GitHub knowledge repo as a structured Markdown file.
+| 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. |
 
-### 3. Connect to Claude Code (optional)
+### Discover
 
-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.
+| 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. |
 
-Run this once:
+### Manage
+
+| 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. |
+
+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.
 
-```bash
-claude mcp add mnemos -- npx mnemos-capture serve-mcp --key <your-api-key>
-```
 
-Now you can say things like:
+## Mobile
 
-- *"Capture this article about prompt caching"*
-- *"What's in my inbox?"*
-- *"Search my captures for evaluation frameworks"*
+Open Mnemos in your phone's browser, tap **Share → Add to Home Screen**. It runs full-screen like a native app.
 
-**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.
+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.
 
-## Mobile access
+## Your data, your storage
 
-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.
+Your knowledge lives in a GitHub repo you own. Plain Markdown files, version-controlled, portable.
 
-## Why GitHub as storage?
+- **No lock-in** — clone it, search it, move it, delete Mnemos tomorrow 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
+- **Any tool can access it** — anything that reads Git or speaks MCP works with your knowledge base
+
+
+## Cost
+
+Mnemos uses your own Anthropic API key (BYOK). You bring your key, Mnemos never charges you for API calls.
+
+Extraction runs on **Claude Haiku 4.5** with prompt caching and input truncation, optimized for minimal token usage:
+
+| Usage | Estimated monthly cost |
+|-------|----------------------|
+| 50 captures/month | ~$0.15 |
+| 100 captures/month | ~$0.30 |
+| 200 captures/month | ~$0.60 |
+
+Less than $1/month for heavy use.
 
-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 · Claude Haiku 4.5 · Anthropic SDK · GitHub OAuth · Vercel Postgres · GitHub Content API · MCP protocol · Tailwind CSS
 
 ## 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)
+- 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)
+- Voice memo capture
+
+
+## Built by
+
+[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},
+    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/hooks.js

@@ -0,0 +1,164 @@
+import { homedir } from "os";
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
+import { join } from "path";
+import { execSync } from "child_process";
+const HOSTED_URL = "https://mnemos-capture.vercel.app/api/mcp";
+const CLAUDE_SETTINGS_PATH = join(homedir(), ".claude", "settings.json");
+// Matches both legacy ("mnemos-capture inbox-check") and modern
+// ("mnemos-capture@latest inbox-check") hook command forms.
+function isMnemosHook(cmd) {
+    return cmd.includes("mnemos-capture") && cmd.includes("inbox-check");
+}
+function readSettings() {
+    if (!existsSync(CLAUDE_SETTINGS_PATH))
+        return {};
+    try {
+        return JSON.parse(readFileSync(CLAUDE_SETTINGS_PATH, "utf-8"));
+    }
+    catch {
+        return {};
+    }
+}
+function writeSettings(settings) {
+    const dir = join(homedir(), ".claude");
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    writeFileSync(CLAUDE_SETTINGS_PATH, JSON.stringify(settings, null, 2) + "\n");
+}
+export function setupHooks(apiKey, opts = {}) {
+    const settings = readSettings();
+    const hooks = settings.hooks ?? {};
+    const sessionStart = hooks.SessionStart ?? [];
+    // Inspect any existing mnemos hook so we can either skip, migrate, or replace
+    let existingCmd = null;
+    for (const group of sessionStart) {
+        for (const h of group.hooks ?? []) {
+            if (typeof h.command === "string" && isMnemosHook(h.command)) {
+                existingCmd = h.command;
+                break;
+            }
+        }
+        if (existingCmd)
+            break;
+    }
+    // skipIfExists (serve-mcp auto-install): preserve user-configured hooks but
+    // silently migrate legacy hooks that don't use @latest so they always stay fresh.
+    if (existingCmd && opts.skipIfExists) {
+        const alreadyLatest = existingCmd.includes("mnemos-capture@latest");
+        if (alreadyLatest)
+            return;
+        // Migration: preserve the existing --briefing flag when upgrading to @latest
+        opts = { ...opts, briefing: existingCmd.includes("--briefing") };
+    }
+    const command = opts.briefing
+        ? `npx -y mnemos-capture@latest inbox-check --key ${apiKey} --briefing`
+        : `npx -y mnemos-capture@latest inbox-check --key ${apiKey}`;
+    // Remove any existing mnemos inbox-check hook (handles key rotation too)
+    const filtered = sessionStart
+        .map((group) => ({
+        ...group,
+        hooks: (group.hooks ?? []).filter((h) => !(typeof h.command === "string" && isMnemosHook(h.command))),
+    }))
+        .filter((group) => (group.hooks ?? []).length > 0);
+    filtered.push({ hooks: [{ type: "command", command }] });
+    settings.hooks = { ...hooks, SessionStart: filtered };
+    writeSettings(settings);
+    if (!opts.silent) {
+        console.log("Mnemos inbox hook installed.");
+        console.log(`Location: ${CLAUDE_SETTINGS_PATH}`);
+        if (opts.briefing) {
+            console.log("At the start of each Claude Code session you'll see a full project briefing.");
+        }
+        else {
+            console.log("At the start of each Claude Code session you'll see your inbox count.");
+        }
+    }
+}
+function run(cmd) {
+    return execSync(cmd, { timeout: 2000, stdio: ["pipe", "pipe", "pipe"] }).toString().trim();
+}
+function detectProjectContext() {
+    const parts = [];
+    // Repo name
+    try {
+        const remote = run("git remote get-url origin");
+        const match = remote.match(/\/([^/]+?)(?:\.git)?$/);
+        const repo = match?.[1] ?? run("git rev-parse --show-toplevel").split("/").pop();
+        if (repo)
+            parts.push(`Project: ${repo}`);
+    }
+    catch {
+        const dir = process.cwd().split("/").pop();
+        if (dir)
+            parts.push(`Project: ${dir}`);
+    }
+    // Current branch
+    try {
+        const branch = run("git branch --show-current");
+        if (branch)
+            parts.push(`Branch: ${branch}`);
+    }
+    catch { }
+    // Recent commits (last 5)
+    try {
+        const log = run("git log --oneline -5");
+        if (log)
+            parts.push(`Recent commits:\n${log}`);
+    }
+    catch { }
+    // CLAUDE.md — first 800 chars gives the model real project intent
+    try {
+        const root = run("git rev-parse --show-toplevel");
+        const claudeMd = readFileSync(join(root, "CLAUDE.md"), "utf-8").slice(0, 800).trim();
+        if (claudeMd)
+            parts.push(`Project instructions (CLAUDE.md excerpt):\n${claudeMd}`);
+    }
+    catch { }
+    return parts.length > 0 ? parts.join("\n\n") : "current project";
+}
+async function callMcp(apiKey, toolName, toolArgs) {
+    const res = await fetch(HOSTED_URL, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${apiKey}`,
+        },
+        body: JSON.stringify({
+            jsonrpc: "2.0",
+            method: "tools/call",
+            params: { name: toolName, arguments: toolArgs },
+            id: 1,
+        }),
+        signal: AbortSignal.timeout(15000),
+    });
+    if (!res.ok)
+        return null;
+    const data = (await res.json());
+    return data.result?.content?.[0]?.text ?? null;
+}
+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");
+            return;
+        }
+        // Default: fast count via list_inbox (no LLM call)
+        const text = await callMcp(apiKey, "list_inbox", {});
+        if (!text)
+            return;
+        // list_inbox returns "N capture(s) in inbox:" or "Inbox is empty."
+        const match = text.match(/^(\d+)\s+capture/);
+        if (!match)
+            return;
+        const count = parseInt(match[1], 10);
+        if (count > 0) {
+            process.stdout.write(`Mnemos: ${count} capture${count === 1 ? "" : "s"} in inbox — run list_inbox to review\n`);
+        }
+    }
+    catch {
+        // Silent fail — never interrupt a session startup
+    }
+}

package/dist/cli/index.js

@@ -8,11 +8,30 @@ async function main() {
         return;
     }
     if (command === "serve-mcp") {
-        // MCP server mode — proxies to hosted instance
         const { serveMcp } = await import("./mcp-server.js");
         await serveMcp();
         return;
     }
+    if (command === "setup-hooks") {
+        const { setupHooks } = await import("./hooks.js");
+        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]");
+            process.exit(1);
+        }
+        setupHooks(apiKey, { briefing: args.includes("--briefing") });
+        return;
+    }
+    if (command === "inbox-check") {
+        const { inboxCheck } = 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 inboxCheck(apiKey, { briefing: args.includes("--briefing") });
+        return;
+    }
     // Default: open the hosted app
     console.log("");
     console.log("  Mnemos — Knowledge capture for agentic workflows\n");
@@ -21,7 +40,7 @@ async function main() {
     console.log("  First time? Sign in with GitHub — setup takes 30 seconds.");
     console.log("");
     console.log("  Connect to Claude Code:");
-    console.log("  claude mcp add mnemos -- npx mnemos-capture serve-mcp --key YOUR_API_KEY");
+    console.log("  claude mcp add mnemos -- npx -y mnemos-capture@latest serve-mcp --key YOUR_API_KEY");
     console.log("");
     // Try to open the URL in the default browser
     const { exec } = await import("child_process");
@@ -33,9 +52,11 @@ function printHelp() {
   Mnemos — Knowledge capture for agentic workflows
 
   Usage:
-    npx mnemos-capture              Open Mnemos in your browser
-    npx mnemos-capture serve-mcp    Start the MCP server for Claude Code
-    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 help                              Show this help
 
   Get started:
     1. Run: npx mnemos-capture
@@ -44,7 +65,15 @@ function printHelp() {
     4. Start capturing!
 
   Connect to Claude Code:
-    claude mcp add mnemos -- npx mnemos-capture serve-mcp --key YOUR_API_KEY
+    claude mcp add mnemos -- npx -y mnemos-capture@latest serve-mcp --key YOUR_API_KEY
+
+  The @latest tag ensures every Claude Code session uses the most recent
+  published version. serve-mcp also self-upgrades on startup as a safety net
+  for users who registered without @latest.
+
+  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
   `);
 }
 main().catch((err) => {

package/dist/cli/mcp-server.js

@@ -33,10 +33,30 @@ export async function serveMcp() {
     const apiKey = keyIdx !== -1 ? args[keyIdx + 1] : undefined;
     if (!apiKey) {
         process.stderr.write("\nMnemos MCP server requires an API key.\n");
-        process.stderr.write("Usage: npx mnemos-capture serve-mcp --key <your-api-key>\n\n");
+        process.stderr.write("Usage: npx -y mnemos-capture@latest serve-mcp --key <your-api-key>\n\n");
         process.stderr.write("Get your API key at: https://mnemos-capture.vercel.app/onboard\n\n");
         process.exit(1);
     }
+    // Self-upgrade: if a newer version exists on npm, respawn via npx @latest.
+    // Handled before anything else so stdio isn't yet owned by the MCP loop.
+    try {
+        const { maybeSelfUpgrade } = await import("./version-check.js");
+        const upgrading = await maybeSelfUpgrade();
+        if (upgrading)
+            return; // child has taken over; parent will exit when child does
+    }
+    catch {
+        // Version check must never block startup
+    }
+    // Auto-install the inbox hook the first time the MCP server is registered.
+    // Uses silent mode so it never prints to stdout (which is reserved for MCP protocol).
+    try {
+        const { setupHooks } = await import("./hooks.js");
+        setupHooks(apiKey, { silent: true, skipIfExists: true });
+    }
+    catch {
+        // Non-fatal — hook setup should never block the MCP server from starting
+    }
     process.stderr.write("Mnemos MCP server starting (proxying to hosted instance)...\n");
     let buffer = "";
     process.stdin.setEncoding("utf-8");

package/dist/cli/version-check.js

@@ -0,0 +1,79 @@
+// Self-update enforcement: ensures users always run the latest mnemos-capture.
+//
+// Strategy: on serve-mcp startup, query npm for the latest published version.
+// If behind, respawn the process via `npx -y mnemos-capture@latest` and proxy
+// stdio. A MNEMOS_UPGRADED=1 env var prevents infinite recursion.
+import { readFileSync } from "fs";
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+import { spawn } from "child_process";
+const NPM_REGISTRY = "https://registry.npmjs.org/mnemos-capture/latest";
+const CHECK_TIMEOUT_MS = 2000;
+export function getCurrentVersion() {
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        // dist/cli/version-check.js → ../../package.json
+        const pkg = JSON.parse(readFileSync(join(here, "../../package.json"), "utf-8"));
+        return pkg.version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+export function isNewer(latest, current) {
+    const l = latest.split(".").map((n) => parseInt(n, 10) || 0);
+    const c = current.split(".").map((n) => parseInt(n, 10) || 0);
+    for (let i = 0; i < 3; i++) {
+        const lv = l[i] ?? 0;
+        const cv = c[i] ?? 0;
+        if (lv > cv)
+            return true;
+        if (lv < cv)
+            return false;
+    }
+    return false;
+}
+async function getLatestVersion() {
+    try {
+        const res = await fetch(NPM_REGISTRY, { signal: AbortSignal.timeout(CHECK_TIMEOUT_MS) });
+        if (!res.ok)
+            return null;
+        const data = (await res.json());
+        return data.version ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * If a newer version exists on npm, respawn via `npx -y mnemos-capture@latest`
+ * with the original argv, piping stdio. Returns true if the caller should stop
+ * (because the child is taking over). Returns false otherwise — caller should
+ * continue with normal startup.
+ */
+export async function maybeSelfUpgrade() {
+    // Recursion guard: the child spawned below will inherit this env var.
+    if (process.env.MNEMOS_UPGRADED === "1")
+        return false;
+    const current = getCurrentVersion();
+    const latest = await getLatestVersion();
+    if (!latest || !isNewer(latest, current))
+        return false;
+    process.stderr.write(`Mnemos: upgrading to v${latest} (was v${current})...\n`);
+    const child = spawn("npx", ["-y", `mnemos-capture@${latest}`, ...process.argv.slice(2)], {
+        stdio: "inherit",
+        env: { ...process.env, MNEMOS_UPGRADED: "1" },
+    });
+    // Keep parent alive until the child exits, then exit with its code.
+    await new Promise((resolve) => {
+        child.on("exit", (code) => {
+            process.exit(code ?? 0);
+            resolve();
+        });
+        child.on("error", () => {
+            // If spawn itself fails, fall through and let the parent continue
+            resolve();
+        });
+    });
+    return true;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mnemos-capture",
-  "version": "1.0.6",
+  "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.",
   "type": "module",
   "bin": {