How do I install Exomem?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Exomem need an API key?

No required environment variable is listed on this record.

What transport does Exomem use?

Exomem runs locally over stdio.

When was Exomem last checked?

Last checked 2026-11-10. Local Markdown/Obsidian knowledge substrate for MCP agents with governed memory and hybrid search.

Exomem MCP server

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

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" }

{"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. Claude Skills are still the best UX where available, but bootstrap() lets generic MCP clients learn Exomem's search/save/upload contract without a separate skill file, including the write loop for compiled notes. See docs/ai-assistant-guide.md for the copyable standing instruction.

claude mcp add exomem -- docker run -i --rm -v "/path/to/vault:/vault" -e EXOMEM_VAULT_PATH=/vault ghcr.io/artexis10/exomem:latest --transport stdio

Use :latest for the lean keyword/BM25 image, :ml for CPU hybrid search, or :cuda for NVIDIA/Linux CUDA capability. CUDA images still boot CPU-default at idle; opt into GPU residency with EXOMEM_MODE=performance when you want it. The image also runs as an always-on remote server via docker compose with a tunnel sidecar — see docs/docker.md. Windows users with a live vault should usually prefer the native install (WSL2 bind mounts miss live file-watch events). macOS cannot serve a vault today: exomem's held-filesystem substrate, which every governed write acquires a reserved-path root through, has a Linux backend and a Windows backend and no darwin implementation, so exomem refuses there and exomem doctor says why.

The first start downloads search models in the background — find works immediately with keyword ranking and upgrades to semantic search automatically once the models land. Run exomem warm to pre-download them ahead of time.

Resource modes

Exomem is CPU-first by default so an idle server does not quietly occupy GPU memory. Control the machine footprint without editing code:

exomem mode quiet          # low-resource: no heavy warm-up, evict caches, defer semantic reindex
exomem mode normal         # default: CPU steady-state, warm CPU caches allowed
exomem mode performance    # explicit opt-in for GPU-capable bulk/model work
exomem status --resources --json

Use quiet before gaming or other foreground workloads. Keyword/BM25 freshness, file-change freshness, inbound links, and resolver state stay live; expensive semantic/CLIP reindex work can be deferred and is reported in resource status. Run exomem index or kb reconcile later to heal deferred semantic work.

Automatic quiet switching is optional. Its watcher skips GPU pressure queries when you select quiet manually, pin a mode with EXOMEM_MODE, or disable EXOMEM_AUTO_QUIET. Automatic quiet still monitors pressure so it can restore the previous mode.

On affected WSL/NVIDIA systems, repeated Linux nvidia-smi processes can grow the Windows driver's kernel memory and disrupt foreground work. Microsoft WSL issue #12756 records a reproduction. For older Exomem versions, a service configured with EXOMEM_AUTO_QUIET=0 stops its watcher after that service restarts. An empty CUDA_VISIBLE_DEVICES also disables GPU work and GPU headroom queries. These settings do not require a Windows reboot; existing driver state may remain.

What it does

Searches the vault you already own. Markdown stays in place; exomem does not import copies into a proprietary note store.
Adopts messy vaults safely. adopt starts with a read-only report and explicit copy and compile-planning options, so originals remain archival until you choose.
Retrieves across text and media. Markdown, PDFs, Office docs, images, screenshots, audio, and video can become searchable through local extraction.
Keeps sources separate from conclusions. Raw captures, compiled notes, entities, evidence, and superseded conclusions live in typed folders.
Surfaces review work. Audit and attention queues can show unprocessed sources, stale notes, broken links, and close-by claims worth reviewing.
Measures, never judges. The server does deterministic work: search, extraction, ranking, embeddings, file writes, and graph checks. Reasoning stays in the client model.

Why use it

Most AI note tools make you move into their app or ingest your files into their store. exomem works the other way around: agents come to your vault.

Compared with	Difference
Doc-chat / RAG apps	exomem works over live files instead of imported copies.
Basic MCP note servers	exomem adds typed knowledge operations, multimodal extraction, audit queues, and CLI/REST parity.
Memory hidden inside one assistant	exomem is client-agnostic: use the same vault from Claude Code, Codex, Cursor, scripts, or a custom chatbot.

For a deeper point-in-time comparison, see docs/comparison-engraph.md. The reproducible graph-only comparison with Basic Memory is in docs/comparison-basic-memory-graph.md. For the practical boundary with chat products' own memory features, see docs/vs-built-in-memory.md.

Measured retrieval quality — and speed. Retrieval is graded by a reproducible golden-set eval harness, not asserted, and latency is measured per lane at corpus scale: hybrid find() runs sub-second end-to-end at 50,000 notes (864 ms on the reference desktop, hot cache off), with the keyword/BM25 lanes served from an FTS5 sidecar index in milliseconds — built into stdlib SQLite, so it works on the lean install too. Methodology and numbers in docs/benchmarks.md.

Simple front door

Agents should route normal user requests through simple actions first, then use the typed tools underneath.

Action	Use when the user says	Backed by
Save	"remember this", "log this", "this is a decision"	`add`, `note`, `link`, `preserve`
Adopt/import	"make this old vault usable", "import my notes safely"	`adopt`, `overview`
Ask	"what do we know about X?", "show the sources"	`find`, `get`
Prove	"save this for the warranty case", "show the evidence"	`preserve`, upload/download, `find`
Review	"what needs cleanup?", "what is stale?"	`attention`, `audit`, `propose_compilation`
Update	"this replaced the old conclusion", "fix that note"	`edit`, `replace`, `reconcile`
Connect	"link this to X", "what should this cite?"	`link`, `suggest_links`
Plan	"save this feature idea", "file this bug for later", "what matters this week"	`plan_memory` with `inspect`, `create`, `query`, `add`, `update`, or `triage`
Record	"log this session", "record this measurement", "update the mileage"	`record_memory` with `inspect`, `create`, `query`, `append`, or `update`

Core tools

exomem exposes typed MCP tools for common knowledge-base work:

Tool	Purpose
`activate_context`	Compile durable context for a raw turn, with no query: resolves which anchors the turn is about and returns a bounded working-memory packet, or abstains.
`episode_memory`	Record a bounded recap of what a conversation worked on, decided and left open, so the next session on any client sees it first; inspect an episode's revisions.
`find`	Search notes, sources, entities, and evidence with type/project/tag filters.
`get`	Read a full page or frontmatter.
`add`	Capture a raw source page.
`note`	Create compiled notes: research note, insight, failure, pattern, experiment, or production log.
`edit`	Patch an existing compiled page.
`replace`	Supersede an old conclusion with a new one and preserve the link between them.
`preserve`	Store binary or text evidence append-only.
`audit`	Check graph and corpus health.
`attention`	Surface review queues such as stale notes, close-by claims, and unprocessed sources.
`overview`	Bounded, read-only structure report of the vault or a subtree — works outside `Knowledge Base/` and before `init`.
`adopt`	Existing-vault adoption: scan-only by default; can save a manifest, copy selected legacy text files as Sources, or return a compile plan while preserving originals.
`record_memory`	One front door for human-owned observed state: inspect, create, query, append, or targeted update a governed Record collection.
`plan_memory`	One front door for human-owned intended future state: inspect, create, query, add, update, or triage a Planning collection.

Tier-2 tools cover governance administration and filesystem escape hatches such as listing directories, creating files, moving pages, trashing files, and recovering from trash. Set EXOMEM_DISABLE_TIER2=1 if you want a smaller tool surface.

Every write records durable history in Knowledge Base/log.md. Service calls also go to logs/exomem.log.

One operation, three doors

Every operation is declared once and exposed through:

MCP for agents.
CLI for terminal and scripts.
REST for personal HTTP integrations when EXOMEM_REST_API_KEY is set.

Examples:

kb find "project handoff" --mode keyword
kb find "stale decision" --json
kb get "Notes/Insights/retrieval-needs-owned-files" --json
kb note --note-type insight --title "Agents need durable context" \
  --content "# Agents need durable context"

curl -s -X POST http://127.0.0.1:8765/api/find \
  -H "Authorization: Bearer $EXOMEM_REST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "project handoff", "mode": "keyword"}'

CLI and REST share the same JSON envelope:

{"success": true, "data": []}

Multimodal by default, resident only while working

The native release-service command installs the standard profile: local embeddings, PDFs/Office documents, OCR bindings, ASR, and CLIP. Heavy models are not loaded at service startup. Media jobs enter a durable queue, run serially in one disposable child process, and the child exits after five idle minutes so its RAM and MPS/MLX/CUDA state return to the host.

Manual/source installs can select the same capabilities directly:

uv sync --extra embeddings
uv sync --extra media

embeddings: local text embeddings plus CLIP image search.
media: OCR for images, PDF extraction, Office document extraction, and faster-whisper ASR for audio/video.

CSV, TSV and JSON evidence uploads get dataset source cards for discovery and exact queries. YAML, JSONL, XML and TOML exports get bounded text previews. These paths need no optional extras; see source formats for limits and governance behavior.

lean and hybrid remain available for constrained machines. Generated image captioning and speaker diarization are advanced opt-ins, not requirements for the standard multimodal path.

System tools: Tesseract is required for image OCR. On Windows:

winget install --id UB-Mannheim.TesseractOCR -e

GPU acceleration is useful but not required. Steady-state torch models default to CPU in normal and quiet; performance is the explicit opt-in for capable NVIDIA CUDA or Apple Silicon MPS/Metal paths. See docs/deployment.md for CUDA, Blackwell, Apple Silicon, diarization, and remote-service details.

Configuration

The server reads environment variables or a .env file. The main ones are:

Variable	Purpose
`EXOMEM_VAULT_PATH`	Vault root containing the governed folder (default `Knowledge Base/`).
`EXOMEM_KB_DIRNAME`	Name of the governed folder inside the vault (default `Knowledge Base`).
`EXOMEM_DISABLE_EMBEDDINGS`	`1` forces keyword/BM25-only search.
`EXOMEM_RECALL_MODEL`	Names the recall encoder. Default: `BAAI/bge-m3` on a personal server and a cloud cell, `BAAI/bge-base-en-v1.5` on a hosted cell. A vault whose vectors came from another model is re-embedded in the background.
`EXOMEM_RECALL_REEMBED`	`off` builds no new sidecar. A personal server keeps serving the old sidecar with its model; a cell keeps dense recall off.
`EXOMEM_DISABLE_TIER2`	`1` hides Tier-2 filesystem tools.
`EXOMEM_REST_API_KEY`	Enables authenticated REST routes.
`EXOMEM_DISABLE_MEDIA_EXTRACTION`	`1` skips server-side OCR/ASR/PDF/Office extraction.
`EXOMEM_DISABLE_CLIP`	`1` disables CLIP image search.
`EXOMEM_MODE`	Hard-pin resource mode: `quiet`, `normal`, or `performance`. Env wins over config.
`EXOMEM_QUIET_MODE`	Legacy truthy alias for `quiet` when `EXOMEM_MODE` is unset.
`EXOMEM_AUTO_QUIET`	`1` enables optional non-torch GPU-pressure auto-quiet switching (default off).
`EXOMEM_DEVICE` / `EXOMEM_TORCH_DEVICE`	Force all torch models to `cuda`, `mps`, or `cpu`. Normally leave unset and use `exomem mode`.
`EXOMEM_MPS_FP16`	On Apple Silicon, run bge/CLIP in fp16 on the Metal GPU — ~half the memory, faster encodes (default on; set to keep fp32).

EXOMEM_CLAIM_NLI_MODEL is retired. Model identity comes only from the in-repo pin registry; a value left in it selects nothing and is reported as ignored by exomem doctor.

The shipped pin is the multilingual MoritzLaurer/mDeBERTa-v3-base-xnli-multilingual-nli-2mil7 checkpoint at one exact upstream revision. Its admission fixtures check English, German, French, Estonian, and mixed English/Estonian examples. That is bounded evidence for those examples, not a promise of equal quality across every language in the model card. Its labels are NLI relations: contradict, duplicate, refine, or neutral. neutral includes unrelated, compatible, and uncertain pairs; it never means “proved unrelated.”

Degradation modes

Optional tiers are absent by default and degrade to silence, not to a substitute. What "absent" means, per tier:

Tier	Install	When absent
Semantic search	`--extra embeddings`	Keyword/BM25 retrieval; every surface still answers.
Media extraction	`--extra media`	Server-side OCR/ASR/PDF extraction is skipped; the model-driven upload `text` path still works.
Vector KNN (`sqlite-vec`)	with `embeddings`	Exact in-memory scan over the same vectors; identical results, more work.
Frozen stance verifier	`--extra nli`	Review-queue entries carry no model polarity label — never a differently-produced label under the verifier's name. Write responses, rankings, and every other surface are byte-identical to a build with no verifier tier at all; only `exomem doctor` names the absence. The verifier runs only under an exact pinned revision and artifact-manifest digest, a versioned label map, and a green bounded multilingual fixture set, and it labels review-queue entries only. Hosted cells do not install or enable it.

Legacy EXOMEM_* names (from the project's former working name, exomem) remain honored: each is promoted to its EXOMEM_* equivalent at startup, with an explicitly set EXOMEM_* value winning on conflict. import exomem and python -m exomem likewise keep working as deprecated aliases.

Remote-only variables and full deployment notes are in docs/deployment.md.

Project status

exomem is packaged on PyPI, uses Release Please for versioning, and follows the lightweight SemVer policy in docs/release.md. The public CLI entry point is exomem; kb is the short daily-driver alias for knowledge-base operations.

License

AGPL-3.0-or-later. See LICENSE.

Exomem

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions