01
One corpus, every assistant
Claude Code, Codex, Gemini, Antigravity, goose, Cursor, Kimi and more read and write the same local memory over MCP. Switch tools mid-project and keep every hard-won detail.
The ship-log for your coding agents
Shared memory, skills and capabilities for every coding agent.
One private ship-log, one synchronized skill library, and one map of what every assistant can actually do. Captain Memo recalls what your agents learned, mirrors the skills they installed, and routes work to the AI that owns the right plugin or extension.
install
git clone https://github.com/kalinbogatzevski/captain-memo
cd captain-memo
bun install
./bin/captain-memo install
Needs Bun 1.1.14 or later. The wizard asks for a summarizer and an embedder; the recommended hosted embedder takes a free Voyage key, and a local one needs none. Full steps
Cross-AI one corpus◆
Native capture as work happens◆
Virtual Skills one catalog◆
Virtual Capabilities one route map◆
Keyless summarizer options◆
Can run fully local◆
Linux · macOS · Windows
One command wires every AI coding tool on the machine (JetBrains takes one paste in the IDE). They all read and write one local corpus.
A shared library and capability map
Virtual Skills explain how. Virtual Capabilities show where.
Captain Memo mirrors the instructions your AIs know and safely publishes the plugins and extensions each runtime can execute. Every connected assistant can discover the best method, find the right owner, and delegate the work without copying secrets or pretending every CLI can run every tool.
Virtual Skills: reusable instructions
Skill discovery is auto by default. Edit or remove the original SKILL.md and its searchable, portable virtual copy updates with it.
Virtual Capabilities: safe delegation
Plugin discovery is also auto by default. Captain Memo publishes only sanitized names, operations and interfaces, then routes execution to the owning AI—never the manifest, credentials or command configuration.
See both in action
captain-memo skill list · captain-memo capability list
Native lifecycle capture
The memory arrives while the work is still happening.
On supported Codex, Gemini CLI and Kimi releases, Captain Memo installs native prompt, tool-result and turn-end hooks. Useful evidence reaches the same local observation pipeline immediately—not after a transcript reader eventually notices the session.
Native when proven
A session becomes native only after its first successful tool event reaches the worker. stats.capture.native shows the proven sessions by CLI.
Fallback without gaps
Older, disabled, untrusted or failed hook installs keep using the existing transcript and rollout readers automatically. Installation alone never switches fallback off.
How native capture works
Codex · Gemini CLI · Kimi · automatic compatibility
Ideas for later
Park the idea. Keep the heading.
A thought for later turns up mid-task. Type it with idea: or todo: in front and it is parked on this machine's homework list; the session says "noted" and the work in hand carries on. Any connected assistant can pick it up later.
Filed without changing course
In Claude Code, and in Codex, Gemini CLI and Kimi where their native hooks are installed, the prompt hook files it before the model acts on it. Everywhere else the model files it with todo_add.
Claimed, then closed
todo_claim marks an item taken, so other sessions see who has it; todo_unclaim hands your own claim back; todo_done closes it with a note. Claude Code shows what is open in its session banner, and Codex and Gemini CLI sessions start with the open list in their context (Captain Memo 0.57.11 or later).
How homework works
todo_add · todo_list · todo_claim · todo_unclaim · todo_done
What a memory store turns into
Enough of it, and the pile has a shape.
Nothing here is tagged, foldered or curated into place. These are 144,159 embeddings from one working store, partitioned with no labels and no supervision — and then read back to see what the partition had found.
Beat one
Every note and captured observation becomes a vector. No schema, no tags, nothing decided in advance.
Beat two
k-means partitions them. 87% of the clusters it finds span more than one repository.
Beat three
Dreaming is a separate pass: where the same fact was learned in separate sessions weeks apart and the notes keep being recalled together, a model names it. Most candidates are declined.
Clusters
The structure already in the store: 477 centroids, and the three kinds of grouping nobody designed. Read the analysis →Dreaming
The offline pass that folds restatements and writes themes, grouped by what you recall together. How it decides →Recall
What the clusters are for: 1166 ms of exhaustive scan down to 47.5 ms, at recall@10 of 0.938. See the arithmetic →Logbook entries
What makes it different.
Not another cloud memory service. A local layer that every AI coding tool on your machine can share.
02
Keyless summarizer options
Summarize with the Claude, ChatGPT, or Google login you already have, or a local model on Ollama. Three of the summarizer backends need no key at all. The recommended hosted embedder takes a free Voyage key; a local embedder needs none.
03
Local-first, and yours
The vector store and metadata live on your disk. Hybrid search (embeddings plus keyword), indefinite retention, and no cloud bill for remembering.
The voyage
Watch, remember, recall.
It runs quietly in the background. You never stop to manage it.
Watch
Captures each working session as structured observations: what changed, what you learned, what to reuse. Which assistants are captured is in the table below.
Remember
Indexes them into a hybrid search corpus, dedupes the noise, and keeps them for as long as you want.
Recall
Injects the relevant memory into every prompt in Claude Code, Codex and Gemini CLI, so the assistant starts already knowing the context. The others, Kimi included, search it through the MCP tools.
The log never goes stale. Every session sharpens the next.
The ship's scribe
How your log gets written.
The summarizer is the scribe of the crew. After each stretch of work it reads what happened, the files you touched, the commands you ran, what you worked out, and writes it up as one short, structured log entry. Those entries are what make your past work searchable later.
Runs on a login you already have
Point it at the Claude, ChatGPT, or Google account you already sign in with, or a local model on Ollama. Three of the choices need no API key at all. It works in the background, a batch at a time, so it never slows a prompt down.
You choose the scribe, and only one sails
Pick a single summarizer when you install. Only one is ever active. See who is on watch any time with captain-memo stats, which names the provider and whether it is actually writing entries.
If the scribe steps away
Nothing is lost, short of a power cut. Your session waits safe in an on-disk queue. A passing outage retries on its own with no penalty. A missing login pauses the writing, and the worker looks at the whole provider list again every 10 minutes, so the queued work is written up by itself once a login works; captain-memo restart does it at once. Claude Code's session banner says Summarizer DOWN, with the reason, while none works. And the rest of your memory, watched files, saved notes, and search, keeps working the whole time. Needs Captain Memo 0.57.6 or later.
The hold
How memory is stored, and found.
Everything you keep is indexed two ways at once, so recall works whether you remember the exact words or only the gist.
Hybrid search
Meaning-based vector search and plain keyword search, fused into one ranking, with a bounded recency boost when your question asks for the latest. Multilingual too: your non-English notes are just as findable.
Your embedder, your call
A tiny hosted model by default (around $0.30 a year of usage, on a free Voyage key), or run it fully local and offline: the bundled local model on Linux and Windows, or Ollama or any /v1/embeddings endpoint on any system, macOS included. Indefinite retention, and no cloud database to rent.
Dreaming — what happens while you're not looking
A corpus that only ever grows eventually crowds out the memories you want. Dreaming folds related observations into a single higher-level theme, and it groups them by what you actually recall together — not merely by what shares vocabulary, which just yields groups that use the same words. The originals are archived, never deleted. It runs on your machine, only while you are away from it, and every change is reversible with one command.
The name is Anthropic's — Claude Managed Agents shipped Dreams in May 2026, a cloud pass that re-reads an agent's transcripts to rebuild its memory store. Captain Memo does the same job locally, and works out what belongs together from co-retrieval rather than by re-reading the text. How dreaming works →
The fleet
Works with what you already use.
Twelve assistants share one memory through Captain Memo's MCP server and a portable skill. One command wires each of them (Claude Code through the plugin, JetBrains with one paste in the IDE). The skill also teaches the work board and homework. Since v0.44.4 a new Claude Code session refreshes those copies after an update; without Claude Code, run connect again.
Claude Code
Codex
Gemini CLI
Antigravity
goose
Cursor
Kimi
opencode
Mistral Vibe
VS Code / Copilot
JetBrains
Claude Desktop
Ollama
LM Studio
any /v1 endpoint
The last three run the summarizer and embedder locally, so a machine with no Claude, ChatGPT, or Google account can still remember, entirely offline.
What each assistant gets. Every one reaches the memory through the MCP tools. Capture as it works, and memory injected into its prompts, depend on what the assistant lets Captain Memo hook into.
| Assistant | Captured as it works | Memory injected into prompts | MCP tools |
|---|---|---|---|
| Claude Code | Yes | Yes | Yes |
| Codex, Gemini CLI | Yes: native hooks where the CLI supports them, otherwise a transcript reader | Yes, where the native hooks are installed | Yes |
| Kimi | Yes: native hooks from Kimi 1.28, otherwise a transcript reader | No: as of Kimi 1.52.0 a prompt hook's output does not reach the model, so Kimi reads memory through the MCP tools | Yes |
| Antigravity, opencode | Yes, from the transcript | No | Yes |
| Cursor, Mistral Vibe, VS Code, goose, Claude Desktop | No | No | Yes |
| JetBrains | No | No | Yes, once you paste the snippet connect writes into the IDE's MCP settings |
Two hands on one file
Run several assistants long enough and two of them will reach for the same file at the same moment. So a Claude Code, Codex or Gemini session publishes a short-lived claim before it touches anything (the edit tools, and sed -i, >, heredocs, tee and the PowerShell write cmdlets too), and every assistant can post one with work_set. The board tells it at once if another agent on the machine holds the same path, the same git checkout, the same topic, or the same problem in different files. The warning names the other session's own files, and a shell edit whose file cannot be named no longer claims the whole repository. What a session declared with work_set survives its later edits until that claim's lease ends.
A live claim blocks. A second session's edit, file-writing shell command or upload of a file that another session has edited in the last 10 minutes is refused: the refusal names the session that holds it and tells the model to stop and ask you. Only you can lift it, by typing override: <file> as your message, and it lasts 30 minutes. A claim that has gone quiet for 10 minutes only warns, and one whose session has exited stops blocking. Only Claude Code, Codex and Gemini sessions are guarded, and Codex and Gemini claims block on Linux; a claim posted by any other assistant only warns. Before an scp, rsync or ssh upload the hook also reads the server copy and refuses when it is not your file, not a committed version and not a copy you fetched, which catches an upload that would overwrite someone else's uncommitted deploy. Claims are leases that expire on their own. CAPTAIN_MEMO_WORKBOARD_ENFORCE=0 in the host's settings env goes back to warnings only.
Claude Code, Codex and Gemini sessions also start with a short set of working rules: look at the board before the first edit, claim every file they will write or deploy, and never edit or deploy over another session's claim.
The captain's manual
Commands and tools.
A handful of commands run it from your terminal. Your assistants get a matching set of tools they call on their own.
In your terminal
Run captain-memo help for the full list.
- captain-memo install
- Interactive setup: embedder, worker, plugin, and your summarizer.
- captain-memo connect <tool>
- Wire another assistant (Codex, Gemini, Cursor, opencode and more) to the shared memory.
- captain-memo doctor
- Health probe across the embedder, worker, and plugin — and, after an upgrade, the sessions still running the old plugin code, named by the daemon that hosts them so you restart the right one. It also warns when more than 2% of chunks have no vector, when a vector-index centre is all zeros, when embedding is paused, and when the plugin cache trails the checkout. Your first stop if anything looks off.
- captain-memo stats · top
- Corpus size and the active summarizer.
topis a live dashboard: sort, filter, drill, an AI-sources chart, and a built-in glossary (?) — see the full stats glossary. - captain-memo upgrade
- Bring the corpus to the current format, end to end (reindex plus compact). Safe to re-run.
- captain-memo maintenance
- Reclaim what nothing needs: spent queue rows, orphaned vectors, and the plugin-cache trees Claude Code marked for collection and never collected. It also lists indexed memory files that are not markdown, which
--applyremoves with their vectors, and chunks whose vector is all zeros, which--applyqueues for re-embedding. Reports first;--applydeletes, and never a tree a live session is loaded from. - captain-memo consolidate · theme
- Run the idle-time pass now instead of waiting (
--for 30mkeeps it going), read the themes it wrote (theme list), and reverse any you disagree with (theme undo <id>). - captain-memo dedup --undo
- Reverse folds: all of them, or only the ones you name with
--member,--run(ids fromdedup --runs) or--since. An undone fold stays undone;dedup --refold-blockslists the marks and--allow-refoldlifts them. The selectors need Captain Memo 0.57.9 or later, the marks 0.57.10,--refold-blocks0.57.11. - captain-memo queue retry
- Return the observations that were given up on while the summarizer had no login to the queue. A dry run until
--apply; each one is a real summarizer call, so--limit Ncaps it. Needs Captain Memo 0.57.6 or later. - captain-memo remember --type decision --body "..."
- Save a durable note by hand — a decision, a preference, a reference — the things you never want it to forget. Pipe a longer one in on stdin.
- captain-memo skill list
- Browse every synchronized virtual skill, optionally filtered by its source AI.
- captain-memo backup create · backup restore
- A portable archive: move your whole memory to another machine.
backup infoinspects one without restoring it.
What your assistant can do
Called automatically over MCP. You never invoke them by hand.
- search_memory
- Find the relevant notes and watched files in your corpus.
- search_observations
- Search the auto-captured log of what you did in past sessions.
- search_all
- One search across everything at once: notes, session log, and skills.
- list_skills · recommend_skills
- Browse the skill catalog or find the few installed skills relevant to the task.
- load_skill
- Load the complete advisory instructions after choosing a virtual skill.
- remember
- Save something worth keeping straight into curated memory.
- get_full
- Pull up a whole document when a snippet is not enough.
- work_set · work_active · work_clear
- The work board: the plugin claims the files this session edits,
work_setadds 1 to 5 tags for what the work is about (kept through later edits until its lease ends), and the session hears at once if another agent on the machine overlaps it. A live Claude Code, Codex or Gemini claim blocks other sessions' edits, file-writing shell commands and uploads; claims expire on their own. - todo_add · todo_list · todo_claim · todo_unclaim · todo_done
- Homework:
idea:ortodo:at the front of a prompt parks it for later, filed by the prompt hook where one is wired and by the model withtodo_addelsewhere. Claude Code lists what is open in its session banner, Codex and Gemini CLI sessions get the list at start, and any assistant can calltodo_list. Claim an item before starting it, hand it back withtodo_unclaim, close it with a one-line note. More on homework → - stats · status
- Report what memory it can see and whether the worker is healthy.
You stay the captain
Your memory never leaves without orders.
The whole corpus, every vector and every note, lives on your own disk. Captain Memo logs the voyage; you decide what, if anything, is ever sent anywhere.
Local by default
Nothing is uploaded for storage. The only things that ever leave are the calls to the summarizer and embedder you chose, and only for the moment they run. An opt-in setting, below, masks credential-shaped values in what a hosted embedder receives.
Fully offline if you want
Run both the summarizer and the embedder on a local model, and nothing at all leaves the machine. No account, no key, no cloud, no exceptions. On macOS the bundled local embedder is not available, so point the embedder at Ollama, LM Studio or any /v1/embeddings endpoint on the machine.
Secrets stay out of recall
A token, key or password kept in a note is blanked out of everything memory hands an assistant: the automatic recall with each prompt and every search snippet. That covers vendor tokens, .env and config values, passwords on command lines and in URLs, and private keys, even one the chunker cut in two.
The real value when you ask for it
Nothing in your notes is changed. Ask for a document by name with get_full and you get it exactly as written. Blanking is tuned against real notes: the word “password”, placeholders and code stay readable.
The worker asks for a secret
Its local API on 127.0.0.1 expects a secret kept in a file only you can read. The hooks, the MCP server and the CLI send it for you, and a wrong secret is always refused. By default a call with no secret is still answered, so sessions started before the upgrade keep working, and captain-memo doctor lists them; set CAPTAIN_MEMO_WORKER_AUTH=enforce once none are left to refuse those calls too.
Masked on the way to a hosted embedder
Off by default. With CAPTAIN_MEMO_EMBED_REDACT=1 in worker.env and a worker restart, credential-shaped values (vendor tokens, password= values, a URL password, bearer and JWT tokens, private keys) are replaced by a placeholder in the copy of the text a hosted embedder receives. Stored notes and local search keep the original, a loopback endpoint (a local sidecar or Ollama) is left alone, and it covers the embedder only, not the summarizer. Pattern-based, so best effort. Needs Captain Memo 0.57.10 or later.
Before you sail
Questions from the dock.
The things people ask before they hoist the plugin.
Do I need a Claude subscription?
No. It works with Codex, Gemini, Cursor and more, and the summarizer can run on your ChatGPT or Google login, or fully local on Ollama. A machine with no Claude at all still remembers.
Will it slow down my prompts?
No. The writing happens in the background between prompts, a batch at a time. You never wait on it, and a whole session becomes a single log entry. The one exception is the opt-in auto-update: the prompt that finds an update check due waits for it, roughly 2 to 8 seconds when nothing is new.
Where does my data live?
On your own disk, under your home directory. There is no cloud database, and nothing is uploaded for storage. The only text that leaves goes to the summarizer and embedder you chose; an opt-in setting masks credential-shaped values in the copy a hosted embedder receives. Needs Captain Memo 0.57.10 or later.
Can I run it completely offline?
Yes. Choose the local embedder and a local summarizer model, and Captain Memo runs with no network at all. On macOS the bundled local embedder is not available: point the embedder at Ollama, LM Studio or any /v1/embeddings endpoint on the machine instead.
Is it really free?
Yes, open source under Apache-2.0. The optional hosted embedder runs about $0.30 a year; keep everything local and it costs nothing. Two guards limit what a hosted embedder can charge for retries: a request that Captain Memo's own timeout cut off is not sent again, and embedding pauses for 30 minutes once more than 500,000 tokens in an hour went to requests that never got an answer. captain-memo stats shows an Embed tokens line with what was sent and the wasted part, and captain-memo doctor names a pause. Needs Captain Memo 0.57.4 or later.
How is it different from a cloud memory service?
It is local, it is shared across all your AI tools instead of locked to one, and it is yours. No Captain Memo account, no lock-in, no per-call bill for remembering.
With Captain Fleet, do captains merge their memories?
No. They share, they never merge. Each captain keeps its own log: what it saw, on its own project, machine and time. Like colleagues, captains ask each other and hear what the other knows; nobody copies a whole memory and nothing becomes one pooled truth. A result from another captain arrives tagged with that captain and the time (per SAMI, 10:05), and it never overrides this captain's own notes. A newer note elsewhere only says when it was written, not that it is true, and SAMI's apples may be different apples. So the answer names its source: "As per SAMI, the apples are 11", not "the apples are 11". Its score counts for less than a local one, and it never outranks this captain's own just by being newer. In automatic recall and search_all, up to two on-topic results from each other captain are guaranteed a place, and those places never push out more than half of this captain's own results.
What if the summarizer stops working?
Nothing is lost, short of a power cut. Your sessions wait in an on-disk queue and get written up once it is back. An outage retries with no penalty, and the rest of your memory keeps working meanwhile. The worker checks the summarizer again every 10 minutes and releases what it had given up on (up to 500 per recovery, and again at each start); captain-memo queue retry --apply releases the rest. Needs Captain Memo 0.57.6 or later.
An idea came mid-task. Where do I put it?
Type it with idea: or todo: at the front of the prompt. In Claude Code, and in Codex and Gemini CLI where their native hooks are installed, the hook files it as homework on this machine before the model acts on it, so the answer is a short "noted" and the work in hand carries on. Kimi's hook files it too, but as of Kimi 1.52.0 the model never sees the filed line and may file a second copy with todo_add; on other assistants the model files it with todo_add. Claude Code lists what is open when a session starts, Codex and Gemini CLI sessions get the same list added to their context (Captain Memo 0.57.11 or later), and any assistant can call todo_list. A session claims an item before starting it, so the others see it is taken, hands its own claim back with todo_unclaim if it cannot do it, and closes it with a one-line note. It is not a memory (a memory is a fact) and not a work claim (a claim is now). More on homework →
What happens while it upgrades itself?
Memory pauses for a few seconds and comes back on its own. A worker that is updating or booting leaves a note saying so, and the session reads it — updating (vX → vY) … memory resumes by itself, no need to restart Claude — instead of declaring the worker dead. The first turn after it is back says so, once. A worker that genuinely will not start is still reported, with the log to look at.
Does it update itself?
A plugin installed from the GitHub marketplace is refreshed by Claude Code, and the worker follows at the next session start. A git-clone install updates itself only if you set CAPTAIN_MEMO_AUTO_UPDATE=1. It then checks about once an hour (less often while checks fail), also from a prompt in Claude Code, so a session left open for days still updates. It fast-forwards to the newest stable release tag, refuses a checkout with local edits, and rolls back if the new worker does not start; a release that failed to start is skipped until a newer one is published. The first session after an update lists the headlines of what changed. If you update a git clone by hand (git pull, bun install, captain-memo restart), the worker is current at once, but Claude Code's hooks run from the plugin cache, which the next session start refreshes; captain-memo doctor warns plugin cache version until then, and captain-memo install --yes refreshes it immediately.
Can I uninstall and come back later?
Yes. captain-memo uninstall takes the worker down and sets your worker.env aside as worker.env.bak — keys, summarizer, embedder, anything you added by hand — and the next install prefills every key, endpoint and model from them — nothing to retype, and a headless install asks nothing at all. Your memory stays on disk unless you pass --purge. On a git-clone install the worker also puts a missing Claude Code plugin back, checking at start and every 30 minutes. An uninstall run as yourself is respected, because it leaves a marker that install clears, but removing the plugin by hand with claude plugin ... while the worker runs is undone unless CAPTAIN_MEMO_PLUGIN_HEAL=0 is set. Needs Captain Memo 0.57.3 or later.
Cast off
Install in four steps.
Clone, install the dependencies, run the wizard. It checks your machine before it touches anything.
- Get Bun. Bun 1.1.14 or later is required; the wizard checks the rest and says how to fix anything missing.
- Clone and run the wizard. Run the first four commands in the box. The wizard asks about five questions. For the summarizer,
captain-memo installchecks which of your Claude, ChatGPT or Google logins is live on this machine and recommends that one (a headless install takes it without asking), or you can point it at a local Ollama model. The recommended hosted embedder takes a free Voyage key (no key handy? the wizard lets you add it toworker.envafterwards); a local embedder needs none. It then sets up the worker, registers the plugin with Claude Code and wires the other assistants it finds. - Restart Claude Code fully: quit the
claudeprocess, not just the session. - Check it. Run
captain-memo doctor, thencaptain-memo stats. From then on memory is captured, indexed and recalled into your prompts.
Runs natively on Linux (systemd --user), macOS (a per-user launchd LaunchAgent — no root) and Windows x64 (a per-user Scheduled Task — no WSL, no admin). One CLI, three supervisors; the wizard picks the right one and checks its prerequisites before touching anything. On macOS, brew install sqlite first — Apple's own SQLite cannot load the vector extension. On Windows, 0.43.4 or later, then captain-memo connect once — earlier builds could not reach the Codex and Gemini hooks or the CLI summarizers there. From a Windows checkout the install command is bun .\bin\captain-memo install.
Advanced, no local worker: if a Captain Memo worker already runs on this machine, or you tunnel to one, claude plugin marketplace add kalinbogatzevski/captain-memo then claude plugin install captain-memo@captain-memo connects Claude Code to it. The plugin only talks to a worker on localhost, so forward a remote worker's port 39888 here, for example with ssh -L 39888:localhost:39888 <host>.
quick start
git clone https://github.com/kalinbogatzevski/captain-memocd captain-memobun install./bin/captain-memo installcaptain-memo doctor