captain-memo

<p align="center"> <img src="docs/logo.png" alt="Captain Memo — The Ship-Log for Your Digital World" width="320"> </p> <h1 align="center">Captain Memo</h1> <p align="center"><em>Your AI fleet's local memory, shared skill library, and runtime capability map.</em></p> <p align="center"> <a href="https://captain-memo.ispcq.com"><b>captain-memo.ispcq.com</b></a> · Built by <a href="https://github.com/kalinbogatzevski">Kalin Bogatzevski</a> · <a href="LICENSE">Apache-2.0</a> · <a href="https://github.com/kalinbogatzevski/captain-memo/issues">Issues</a> </p>

Captain Memo is a Claude Code plugin — and a cross-AI local intelligence layer: one local corpus shared by every MCP-speaking coding agent on your machine (Claude Code, Codex, Gemini CLI, Antigravity, goose, Cursor, opencode, Kimi CLI). What one tool learns, the others recall; skill instructions installed for one AI become reusable Virtual Skills; and sanitized Virtual Capabilities tell the crew which runtime owns a plugin or extension that can execute a task.

Memory is only the beginning. Captain Memo automatically synchronizes complete skill instructions, lists them for every connected AI, and maps runtime-specific plugins without copying commands, credentials, or executable configuration. An AI can learn a shared method locally, or discover that (for example) an image tool lives on Gemini and delegate the work there. See how Virtual Skills & Capabilities work →

<p align="center"> <img src="docs/demo.gif" alt="Terminal recording: `captain-memo connect` wires six installed AI tools to one shared worker, then `captain-memo stats` shows four of them writing into the same local corpus" width="820"> </p> <p align="center">_{One command wires every AI coding tool on the machine. They all read and write <b>one</b> local corpus.}</p>

Platforms — Linux, macOS and native Windows (x64). Linux runs under systemd --user; macOS runs as a per-user launchd LaunchAgent (no root — see macOS below); Windows runs natively under a per-user Scheduled Task (no WSL, no admin) — see Windows (native), or the WSL2 fallback. One ServiceManager interface, three supervisors; the CLI is identical on all three.

---

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), goose, 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. Current Codex, Gemini, and Kimi releases also get native lifecycle hooks for automatic recall and observation capture; older or disabled hook implementations stay on the transcript reader automatically. See docs/cross-ai-tools.md.
• Auto-discovered memory — every assistant, not just Claude. CAPTAIN_MEMO_WATCH_MEMORY=auto (the install default) probes the machine and indexes whichever AI memory files actually exist: ~/.claude/CLAUDE.md, per-project Claude memories, ~/.codex/, ~/.gemini/, ~/.cursor/rules/, repo-level AGENTS.md / CLAUDE.md / .github/copilot-instructions.md. Each doc is tagged with the tool it came from. Composes with your own globs (auto,/my/notes/*.md). Credentials and session logs are structurally unindexable — every discovery glob must end in .md/.mdc, which is enforced by a test, not a blocklist.
• Virtual Skills — one synchronized skill repository for every AI. Captain Memo mirrors the user-level SKILL.md files installed for Claude Code, Codex, Gemini, Cursor, opencode, Vibe, Kimi and more into its local SQLite corpus, preserving complete instructions, provenance, hashes and portability warnings. Discovery is AUTO when CAPTAIN_MEMO_WATCH_SKILLS is missing; set it to an explicitly empty value to opt out. Native files remain canonical and edits/deletions synchronize live. Humans can browse with captain-memo skill list; connected assistants use list_skills, recommend_skills and load_skill. Imported instructions remain advisory, and the existing backup/restore path carries the repository with the rest of Captain Memo.
• Virtual Capabilities — the fleet knows where work can actually run. Captain Memo auto-discovers installed Gemini/Agy extensions plus Claude and Codex plugins, then stores a sanitized descriptor in the same SQLite corpus: name, description, version, operation names, interface names, and owning runtime. It never imports command bodies, executable configuration, environment values, or credentials. Use captain-memo capability list, capability recommend, or the list_capabilities / recommend_capabilities / get_capability MCP tools. A result says “delegate this to Gemini on this captain,” not “pretend this plugin runs in every CLI.” Missing CAPTAIN_MEMO_WATCH_CAPABILITIES means AUTO; explicitly empty opts out.
• 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.
• Six summarizer providers, picked at install time — three of them need no API key at all:
  • 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.
  • codex — codex exec on your ChatGPT Plus/Pro account. No API key, no Anthropic subscription needed. The zero-key option if you don't have Claude Max. ~6–7 s/call (that's Codex booting its agent runtime, not inference — it's flat across the model ladder, so a small model saves quota, not time). Uses your account's own model by default (no slug to keep current). Runs on the background tick, so it never blocks a prompt. Requires codex login.
  • agy — Antigravity CLI on a plain Google account. The widest-reach zero-key option: no Claude plan, no ChatGPT plan, no API key. ~3–5 s/call (measured on Gemini 3.5 Flash (Low)) — the fastest of the three agent-CLI transports. Uses your account's own model by default. Runs under an isolated $HOME, so it never touches your real agy --continue history. Needs agy ≥ 1.1.1.
  • 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 <memory-context> envelope is added to every user prompt in Claude Code and in native-hook-capable Codex, Gemini, and Kimi releases. The model sees relevant memory, skills, and prior session observations before it answers.
• Session observations. Tool-use events from Claude Code and native-hook-capable Codex, Gemini, and Kimi sessions are captured immediately; transcript readers cover older CLIs plus Agy and opencode. Batched events are summarized into structured observations (type / title / facts / concepts) and indexed into the same hybrid search. Native and transcript paths deduplicate per session.
• 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.

One machine is free, forever. Everything above runs on your own hardware — no account, no server, no key required for the zero-key paths. Nothing is time-limited, feature-gated, or held back. If you end up running agents across several machines and want them to share one memory, that's Captain Fleet, a separate commercial relay. It is not a trial and this is not a crippled edition; a single machine is the whole product for most people, including me on most days.

---

Requirements

Always required:

| Component | Minimum | Notes | |---|---|---| | OS | Linux (systemd), macOS, or Windows x64 | macOS uses a per-user launchd LaunchAgent and needs brew install sqlite (Apple's SQLite cannot load the vector extension); Windows uses a per-user Scheduled Task. win32-arm64 unsupported — run x64 Bun under emulation. | | 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](https:/