exomem

<!-- mcp-name: io.github.Artexis10/exomem -->

Durable memory with sources, proof, history, and review for MCP-capable agents.

exomem turns an owned Markdown/Obsidian vault into a local knowledge substrate for Codex, Claude Code, Cursor, chatbots, CLI agents, and any client that can call MCP tools. Your files stay plain, local, portable, and editable outside the server.

agent -> MCP tools -> exomem -> your Markdown / Obsidian vault

Prove it in 30 seconds

uvx exomem demo

One command, no install, no config, no vault of your own needed:

exomem demo — bundled sample vault, keyword mode, fully local
vault: /tmp/exomem-demo-XXXXXX

1. doctor: PASS (0.8s)
2. find "retrieval": PASS (0.1s)
   - Knowledge Base/Sources/Sessions/2026-06-30-sample-session.md
   - Knowledge Base/Notes/Insights/retrieval-needs-owned-files.md
3. get retrieval insight: PASS (0.0s)
   - title: Retrieval needs owned files
   - type: insight
   - excerpt: Local-first knowledge tools should retrieve from files the user already owns.
4. audit: PASS (0.0s)

demo PASS — total 1.0s. This is your proof: agents search files you own.
Next: connect your own vault with `exomem setup`

Runs fully local and read-only against a sample vault bundled in the package. Add --keep to leave that copy on disk afterward and open it in Obsidian.

Install in one line

Mac / Linux — paste into Terminal:

curl -fsSL https://raw.githubusercontent.com/Artexis10/exomem/main/scripts/install.sh | sh

Windows — paste into PowerShell:

irm https://raw.githubusercontent.com/Artexis10/exomem/main/scripts/install.ps1 | iex

Either one installs uv, installs exomem, and walks you through exomem setup, which wires up every agent client on the machine — Claude Code and Codex both get the MCP server, all ten skills, and the capture/retrieve hooks.

Safe to run again later — it skips whatever's already done. If it can't prompt you interactively (e.g. run from another script), it prints the exact command to run next instead of guessing. Prefer to run each step yourself? See below or the full manual walkthrough in QUICKSTART.md.

Claude Code: install as a plugin

The plugin carries the skills and hooks. Its MCP entry is an optional shared HTTP URL; it deliberately does not auto-start a full stdio server in every Claude Code session:

/plugin marketplace add Artexis10/exomem
/plugin install exomem@exomem

Then choose the route. If you already run Exomem as a service for phone or hosted access, reuse that one authenticated core:

exomem setup --vault "/path/to/vault" --mcp-url https://<host>/mcp

For local-only use, run exomem setup --vault "/path/to/vault" --stdio. Stdio is intentionally explicit because each client session owns its process and can load its own embedding runtime. When updating from an older plugin, run /plugin update exomem@exomem, then /reload-plugins or restart Claude Code before rerunning setup.

claude.ai and ChatGPT

Neither platform can install skills programmatically — upload is manual. Build the archives, then upload them in the client's settings:

exomem package-skills          # writes dist/skills/*.zip (all ten)

Point the client at your server as a connector (see docs/remote-quickstart.md). Neither platform has a hook system, so capture there is skill-driven rather than automatic.

Set it up in 5 minutes

uv tool install exomem   # or: pip install exomem
exomem setup --vault "/path/to/your/Obsidian"

Re-running the one-line installer upgrades an existing uv-tool install instead of leaving an older exomem command on PATH. exomem --version --json is a model-free provenance check, so it also works in the intentional lean CLI paired with a fuller managed service.

One command does the whole local setup: the wizard scans your vault and shows what's already there, initializes Knowledge Base/, runs the doctor preflight, registers the server with every client it detects (Claude Code and Codex), and installs the skills into each.

If cwd .env or the process contains EXOMEM_BASE_URL, setup registers its canonical /mcp endpoint with Claude Code and Codex so they share the existing service. Otherwise it uses the explicit local stdio fallback. Use --mcp-url to choose a service directly, --stdio to force local stdio, and --replace-client-registration when you deliberately want to replace an existing manual route. Native clients handle OAuth; setup never stores bearer tokens.

Config files it did not create are treated as yours: it merges rather than overwrites, backs the file up first, and prints the diff.

Already have a vault full of notes? That's the normal case: adopt gives a scan-first, read-only report of what's there, suggested knowledge packs, and safe copy/compile-planning next actions. Exomem only ever writes under Knowledge Base/ — your existing files stay untouched unless you explicitly copy or compile selected material. See QUICKSTART.md § Already have a vault full of notes? for the full contract, including daily-notes vaults. Re-running setup is safe; completed steps report [skipped]. Non-interactive: exomem setup --yes --vault "/path" --lean.

The individual steps (exomem init / doctor / install-skill / install-hook, plus claude mcp add) still exist as the manual path — see QUICKSTART.md.

The skill installs under the Claude Code name exomem — the same name as the connector, so skill, server, and tools all read as one product. The skill is recommended for Claude Code — the server gives Claude the tools, the skill is what makes it use them. Hooks are local-client reliability helpers for Claude Code and Codex: a read-side reminder before answers, a write-side reminder at natural stopping points, and a shared local continuation checkpoint around compaction. The checkpoint stores bounded structural evidence (repository state, artifact hashes/counts, and transcript provenance hashes), never conversation, tool, summary, or artifact content. It needs no MCP connection or Exomem credential. The read-side hook suppresses obvious control/status prompts like continue, merge it, and are you done?, and can optionally upgrade that reminder to real retrieved KB content (EXOMEM_RETRIEVE_INJECT=1, opt-in; the legacy KB_RETRIEVE_INJECT name still works) — or, with EXOMEM_RETRIEVE_INJECT=working_set, to a compiled activate_context packet under a data header, bounded by EXOMEM_RETRIEVE_INJECT_MAX_CHARS (default 4,000). For Codex, run exomem install-hook --client codex; for Claude Code, exomem install-hook — see QUICKSTART.md § 7. Both clients checkpoint on manual or automatic PreCompact and reinject on SessionStart(compact|resume); Claude also checkpoints on SessionEnd. Pinned Codex CLI 0.144.3 has no SessionEnd hook, so Exomem does not invent one. Other MCP clients can still use the server. If they do not support Skills, have them call bootstrap() once at the start of the session; it returns the same compact operating contract through MCP, including when to search, when to save, workflow-skill discovery, upload guidance, and performance profiles. It also teaches the authoring loop: search first, draft the typed note, run suggest_links, write with the right tool, inspect warnings/suggestions, then report the path.

How eagerly it does that is tunable: four prominence levels (off / light / balanced / maximal), set with exomem prominence <level> or pasted into a web assistant's custom instructions. Clients with hooks default to balanced; web and hosted default to maximal, because nothing there re-arms the check between turns. See docs/prominence.md for the levels and the copy-paste blocks.

For client-specific assistant instructions, see docs/ai-assistant-guide.md. For the boundary between Exomem and a chat product's built-in memory, see docs/vs-built-in-memory.md.

Full local setup is in QUICKSTART.md. Remote/mobile setup is in docs/remote-quickstart.md and docs/deployment.md.

Remote OAuth uses GitHub once to prove the configured login plus immutable user ID, then issues an Exomem-owned durable session. Operators can inspect and revoke those sessions with exomem auth sessions, exomem auth revoke <session-id>, and exomem auth revoke --all; session administration is never an MCP tool.

The product model is intentionally simple: built-in AI memory remembers preferences and routing, while Exomem stores durable governed knowledge with sources, proof, history, decisions, records, and review. See docs/product-model.md for the full mental model, docs/records.md for human-owned longitudinal Records, docs/tui.md for the interactive terminal UI (exomem tui, optional tui extra), docs/review-studio.md for the packaged browser review loop, docs/epistemic-inbox.md for daily review and relation repair, docs/knowledge-packs.md for pack/admin details, and docs/workflow-skills.md for the named agent workflows.

For development, or to run the sample vault from a checkout instead of a package install:

git clone https://github.com/Artexis10/exomem.git
cd exomem
uv sync
uv run exomem demo

Connect your agent

| Client | How | | --- | --- | | Claude Code | exomem setup registers it for you (see above) | | Codex CLI | codex mcp add plus optional exomem install-hook --client codex - see docs/ai-assistant-guide.md#codex-cli | | claude.ai or hosted chat | Remote MCP/connector - see docs/remote-quickstart.md and docs/ai-assistant-guide.md#hosted-chat-clients | | Any MCP client | Generic stdio config - see below and docs/ai-assistant-guide.md#generic-stdio-mcp-clients; call bootstrap() first | | Docker (no Python) | One docker run line — see below and docs/docker.md |

<details> <summary>Codex CLI</summary>

codex mcp add exomem --env EXOMEM_VAULT_PATH="/path/to/vault" -- exomem --transport stdio

Optional local hooks, using the same Exomem scripts as Claude Code:

exomem install-hook --client codex

Verify deployed Claude Code/Codex hooks without changing anything:

exomem install-hook --check

For the AGENTS.md instruction block and the "do not search every tiny prompt" policy, see docs/ai-assistant-guide.md.

Or add it directly to ~/.codex/config.toml:

[mcp_servers.exomem]
command = "exomem"
args = ["--transport", "stdio"]
env = { EXOMEM_VAULT_PATH = "/path/to/vault" }

</details> <details> <summary>Any MCP client (generic stdio)</summary>

{"mcpServers": {"exomem": {"command": "exomem", "args": ["--transport", "stdio"], "env": {"EXOMEM_VAULT_PATH": "/path/to/vault"}}}}

After connecting, ask the agent to call bootstrap() before using the KB.