Captain Memo

Captain Memo

Your AI coding agent's logbook — local memory, kept in sync, retrieved on every prompt.

Built by Kalin Bogatzevski · Apache-2.0 · Issues

Captain Memo is a Claude Code plugin — and a cross-AI local-memory layer: one local corpus shared by every MCP-speaking coding agent on your machine (Claude Code, Codex, Gemini CLI, Antigravity, Cursor, opencode, Kimi CLI), so what one tool learns, the others recall. Every session leaves a wake; Captain Memo keeps the log so the next session — in any of your AI tools — sails with what was learned in the last one.

> Platforms — Linux + native Windows (x64). Linux runs under systemd --user; Windows runs natively under a per-user Scheduled Task (no WSL, no admin) — see [Windows (native)](#windows-native) below, or use the [WSL2 fallback](#wsl2-fallback). macOS support is still pending; Mac users can run the worker manually under launchd / tmux / nohup, see issue #1.

---

Why I built this

I run an ISP and built the ERP platform behind it. The same platform now runs at a friend's ISP in another country, and most of the code that keeps both deployments alive passes through Claude Code on its way to production. Billing fixes, NAS migrations, OLT integrations, GitLab tickets that drag on for weeks. The kind of work where the context is half the job.

Sometime in the last year, my AI pair-programmer became my most patient colleague. It would sit through a four-hour debugging arc with me, never tire, never lose the thread inside that session. But the moment a session ended, every hard-won realisation went with it. The next morning I'd open a new chat and re-explain why we don't round in the middle of a billing calculation, why bills on one tenant are trigger-driven, why we never clone $smy in CLI smoke tests. The same lessons. Every. Single. Day.

I tried writing things down. The ~/.claude/memory/ folder filled up — feedback rules, project notes, references, observations from incidents. Hundreds of small markdown files, each a hard-earned scrap of judgment. Then claude-mem came along and made some of that searchable, and for months it was my colleague's memory. It helped me a lot. Without it, Captain Memo wouldn't exist — because I wouldn't have known what shape the problem really had.

Eventually I started noticing the gaps for the way I work: small English-only embeddings, opinionated retention, one cloud LLM. My Bulgarian-and-English notes returned no hits on the Bulgarian half. Some retrievals felt random on a corpus this size. None of that takes away from how useful claude-mem still is — it just turned out my work needed something a little different.

So I sat down to build that "something different" for myself, and ended up with something I think other people might want too.

---

What it is

• Local-first. Vector store and metadata live on your machine — sqlite-vec + SQLite WAL. No cloud database, no per-call billing for retrieval, no network round-trips on the hot path.
• Cross-AI — one corpus, many tools. Claude Code, Codex, Gemini CLI, Antigravity (agy, the Gemini-CLI successor), Cursor, opencode, Mistral Vibe, Kimi CLI, VS Code (Copilot), and JetBrains (AI Assistant) all share the same local memory through Captain Memo's MCP server + a portable skill. captain-memo install (or captain-memo connect) auto-detects the AI tools on your machine and wires each one — no manual setup. Verified live: Codex and Gemini CLI recalling an observation Claude Code captured, from the same worker; the rest are supported via their standard MCP config (JetBrains is IDE-only config, so connect drops a paste-ready snippet instead of auto-wiring). See [docs/cross-ai-tools.md](docs/cross-ai-tools.md).
• Hybrid search. Voyage embeddings (default) + SQLite FTS5 keyword index, fused by weighted cosine + BM25 scoring (RRF still available via the legacy rank profile), with a recency-aware re-rank on observations. Multilingual (BG/EN/etc.) — your non-English memory is searchable too.
• Four summarizer providers, picked at install time:
• claude-oauth (default) — direct Anthropic API using the OAuth token Claude Code already stored. No API key. ~700 ms/call. Just works on a Max plan.
• anthropic — direct Anthropic SDK with ANTHROPIC_API_KEY (paid)
• claude-code — claude -p subprocess (slower; for users without OAuth file access)
• openai-compatible — Ollama / LM Studio / vLLM / OpenAI / OpenRouter / DeepSeek / Groq / Together / Mistral / etc.
• Four embedder backends, picked at install time:
• voyage-hosted (default) — Voyage API (voyage-4-lite, 1024-dim). Free signup, ~$0.30/year typical use, fast on any hardware.
• local-sidecar — voyageai/voyage-4-nano open weights via a self-contained FastAPI sidecar (offline, private, 2048-dim, AVX2 recommended)
• openai-compatible — Any /v1/embeddings endpoint (Ollama, OpenAI, OpenRouter, etc.)
• skip — keyword-only retrieval (FTS5 only, no vectors)
• Auto-injected context. A ` envelope is added to every user prompt by the UserPromptSubmit` hook. The model sees relevant memory, skills, and prior session observations before it answers.
• Session observations. Every tool use is captured fire-and-forget; on Stop, batched events are summarized into structured observations (type / title / facts / concepts) and indexed into the same hybrid search. Future sessions can recall them.
• Work-coordination board. Before every Edit/Write/MultiEdit/NotebookEdit, a PreToolUse hook publishes a transient "I'm touching these files" claim to a shared board. Any other AI tool on the same machine editing overlapping files is flagged instantly — by file path, and by meaning (a semantic pass catches two agents working on the same thing in different files, which a plain glob match misses). Advisory only, never blocks an edit; claims are leases that auto-expire, so a crashed session never leaves a phantom claim behind.
• Indefinite retention. No 30-day cleanups. A project takes years; your memory should too.

---

Requirements

Always required:

| Component | Minimum | Notes | |---|---|---| | OS | Linux (systemd) or Windows x64 | Windows uses a per-user Scheduled Task; win32-arm64 and macOS not yet supported | | Bun | ≥ 1.1.14 | https://bun.com | | Disk | ~50 MB | The corpus itself + worker code; grows ~1 MB per few hundred chunks | | Sudo | not required | The default install runs entirely as your user. Sudo only needed for --system (multi-user / always-on server). |

Plus, depending on the embedder you pick:

| If you choose | Extra requirement | Approx footprint | |---|---|---| | Hosted Voyage API (recommended) | Free API key from dash.voyageai.com, outbound HTTPS | ~$0.30/year typical use, no install bloat | | Local voyage-4-nano sidecar | Python 3.11+, AVX2 CPU recommended (works without — ~10× slower), 4 GB RAM, ~6 GB disk | Self-contained but heavy; bring patience for first-time pip install + model download | | Other OpenAI-compatible endpoint (Ollama, OpenAI, OpenRouter) | Whatever your endpoint requires | Depends on backend |

And, depending on the summarizer you pick:

| If you choose | Extra requirement | |---|---| | Claude Max via OAuth (recommended) | A Claude Max subscription + claude login already done. No API key. | | Anthropic API | ANTHROPIC_API_KEY=sk-ant-… (paid per token) | | Claude Code subprocess | claude CLI on PATH; uses Max plan but adds 5–15 s per call vs OAuth | | OpenAI / Ollama / OpenRouter | Endpoint URL + optional API key |

The install wizard runs pre-flight checks before touching anything — it tells you exactly which requirement is unmet and how to fix it. If your CPU can't run the local embedder, the wizard recommends a hosted backend instead.

Install — pick a path

All paths lead to the same plugin loaded into Claude Code. The wizard asks which embedder + summarizer to use, then sets everything up.

git clone https://github.com/kalinbogatzevski/captain-memo
cd captain-memo
bun install
./bin/captain-memo install

The wizard asks ~5 questions and sets up:

• Worker daemon at ~/.config/systemd/user/captain-memo-worker.service (port 39888)
• Plugin registration via claude plugin marketplace add + claude plugin install — your hooks, MCP server, and slash commands all auto-register
• Config at ~/.config/captain-memo/worker.env
• CLI shim at ~/.local/bin/captain-memo (/usr/local/bin in system mode)
• Cross-AI wiring — auto-detects the other AI tools on the machine (Codex, Gemini CLI, Cursor, opencode, …) and points each at the same worker (re-runnable anytime with captain-memo connect; skip with --no-cross-ai)
• Embedder sidecar at ~/.captain-memo/embed/ (only if you pick the local backend)

After the wizard, fully restart Claude Code (quit the claude process, not just the session) for the plugin to load.

What the wizard asks you

Question 1 — Summarizer (compresses tool-use events into observation chunks):

| Pick | When | |---|---| | Claude Max via OAuth (recommended) | You have a Claude Max subscription. Free, fast (~700 ms/call), no API key — Captain Memo reads the OAuth token Claude Code already stored. | | Anthropic API | You want explicit per-token billing or don't have Max. | | Claude Code subprocess | OAuth not available; falls back to spawning claude -p per call (slower). | | OpenAI / Ollama / OpenRouter | You're routing to a different model fleet. | | Skip | Events queue but don't summarize (rare; you keep raw events for later). |

Question 2 — Embedder (turns text into vectors for semantic search):

| Pick | When | |---|---| | Hosted Voyage API (recommended) | Best for most users. Fast on any hardware, ~$0.30/year typical use, free signup at dash.voyageai.com. 1024-dim. | | Local voyage-4-nano sidecar | You want offline / fully-private inference. Needs AVX2 CPU + 6 GB Python install. 2048-dim. | | External /v1/embeddings | Self-hosted (Ollama, vLLM, llama.cpp), or another hosted provider. | | Skip | Keyword-only retrieval (FTS5, no vectors). Search quality drops a lot. |

If you pick Voyage hosted and don't have your API key handy, leave it blank — the wizard writes worker.env without a key and tells you to add one before starting; put a CAPTAIN_MEMO_EMBEDDER_API_KEY=… line in worker.env and restart the worker.

Question 3 — Watched memory files (which markdown the worker indexes and keeps in sync):

| Pick | When | |---|---| | All Claude project memories (recommended) | Index every project's ~/.claude/projects/*/memory/*.md. | | User-global only | Just ~/.claude/memory/*.md. | | Custom paths | You keep memory files elsewhere — the wizard prompts for comma-separated globs. | | Skip | No file watching; observations only. |

System-wide install (headless servers, multi-user)

For headless boxes, multi-user dev servers, or "always-on regardless of who's logged in":

sudo ./bin/captain-memo install --system

Installs to /opt/captain-memo-embed/ + /etc/systemd/system/ + /etc/captain-memo/ instead of $HOME. Same wizard, same result, just at system scope. Survives any user logout.

Plugin-only install (advanced, no local worker)

If you already have a Captain Memo worker running on another box and just want THIS Claude Code install to talk to it:

claude plugin marketplace add kalinbogatzevski/captain-memo
claude plugin install captain-memo@captain-memo

The plugin only ever talks to a worker on localhost (CAPTAIN_MEMO_WORKER_PORT overrides the port, not the host), so forward the remote worker's :39888 onto this machine's localhost — e.g. ssh -L 39888:localhost:39888 . This is a power-user setup; most people should run the wizard.

Updating

claude plugin update captain-memo@captain-memo

Use the fully-qualified id (captain-memo@captain-memo). The simplest upgrade is to re-run captain-memo install — it refreshes Claude Code's plugin cache for you. (A directory-source marketplace is snapshotted at add time, so a bare claude plugin marketplace add is a no-op once it exists; the installer does marketplace remove→add to force a fresh copy of the current hooks + bundle.) To refresh by hand instead: claude plugin marketplace remove captain-memo then claude plugin marketplace add . A GitHub marketplace re-fetches on its own.

Auto-updates. Install the plugin from the GitHub marketplace (claude plugin marketplace add kalinbogatzevski/captain-memo) and Claude Code re-fetches new versions on its own — no git required. When a newer version goes live, Captain Memo's SessionStart hook self-heals the worker to it and shows a one-time ⚓ Captain Memo self-upgraded: vX → vY banner. It only ever touches the plugin + worker process — never your worker.env, config, or corpus. Opt out of the auto worker-restart with CAPTAIN_MEMO_DISABLE_SELF_HEAL=1. (The local-clone full install is a directory-source snapshot Claude Code doesn't auto-refetch, so there you upgrade by re-running captain-memo install.)

Windows (native)

Captain Memo runs natively on Windows x64 — no WSL required.

git clone https://github.com/kalinbogatzevski/captain-memo
cd captain-memo
bun install            # MUST run on Windows x64 — see note below
bun .\bin\captain-memo install

Requirements and behavior on the native path:

• Bun on PATH (bun.com). The same bun runs the worker, the MCP server, and the hooks.
• Run bun install on the Windows x64 machine. sqlite-vec ships its native loadable extension per-platform; the x64 install pulls in vec0.dll. A node_modules copied from Linux/macOS lacks the DLL and the worker can't load vectors. win32-arm64 is unsupported — on ARM64 hardware, run x64 Bun under emulation.
• Hosted Voyage is the default embedder — pure HTTPS, nothing local to install or misconfigure. The local Python sidecar (local-sidecar) is still available on Windows via a PowerShell installer if you want offline embeddings.
• Supervision is a per-user Scheduled Task, not systemd. The wizard registers captain-memo-worker to start at logon with restart-on-failure — no admin / UAC prompt. Config lives at %APPDATA%\captain-memo\worker.env.

After the wizard, fully restart Claude Code (run it on Windows too) for the plugin to load.

Upgrading on Windows

To move an existing native install to a newer release:

# The worker runs from your checkout; find it if you're unsure:
#   (Get-ScheduledTask -TaskName 'captain-memo-worker').Actions[0].WorkingDirectory
cd 
git pull
bun install                       # refresh deps (and vec0.dll) on this x64 box
Stop-ScheduledTask -TaskName 'captain-memo-worker'; Start-ScheduledTask -TaskName 'captain-memo-worker'
captain-memo doctor               # confirm the worker is healthy on :39888

The Windows CLI shim runs the TypeScript source directly (captain-memo.cmd → bun "\src\cli\index.ts"), so git pull makes the new CLI live with no rebuild — captain-memo help then prints the new version. Re-running bun .\bin\captain-memo install is an equivalent, idempotent alternative: it replaces the Scheduled Task in place (schtasks … /F) and re-grants permissions. If captain-memo isn't on PATH, prefix every command with bun bin\captain-memo from the checkout.

Re-running bun .\bin\captain-memo install also refreshes the plugin cache for you (it does marketplace remove→add), so the cached hooks and MCP bundle always match your checkout — there's no separate claude plugin update step to remember. captain-memo doctor sho

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: kalinbogatzevski
• Source: kalinbogatzevski/captain-memo
• License: Apache-2.0
• Homepage: https://github.com/kalinbogatzevski/captain-memo

Install and usage instructions live in the source repository linked above.