exomem

# exomem

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

[![PyPI](https://img.shields.io/pypi/v/exomem.svg)](https://pypi.org/project/exomem/)
[![Python](https://img.shields.io/badge/python-%3E%3D3.11-3776ab.svg)](https://pypi.org/project/exomem/)
[![CI](https://github.com/Artexis10/exomem/actions/workflows/ci.yml/badge.svg)](https://github.com/Artexis10/exomem/actions/workflows/ci.yml)
[![License: AGPL-3.0](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)](LICENSE)

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.

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

## Prove it in 30 seconds

```bash
uvx exomem demo
```

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

```text
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:

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

**Windows** — paste into PowerShell:

```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](https://github.com/Artexis10/exomem/blob/main/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:

```bash
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:

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

Point the client at your server as a connector (see
[docs/remote-quickstart.md](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

```bash
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?](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](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). For Codex, run
`exomem install-hook --client codex`; for Claude Code, `exomem install-hook` —
see
[QUICKSTART.md § 7](QUICKSTART.md#7-recommended-make-the-kb-automatic-both-directions).
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.

For client-specific assistant instructions, see
[docs/ai-assistant-guide.md](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](docs/vs-built-in-memory.md).

Full local setup is in [QUICKSTART.md](QUICKSTART.md). Remote/mobile setup is
in [docs/remote-quickstart.md](docs/remote-quickstart.md) and
[docs/deployment.md](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](docs/product-model.md) for the full mental model, [docs/review-studio.md](docs/review-studio.md) for the packaged browser review loop, [docs/epistemic-inbox.md](docs/epistemic-inbox.md) for daily review and relation repair, [docs/knowledge-packs.md](docs/knowledge-packs.md) for pack/admin details, and [docs/workflow-skills.md](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:

```bash
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](docs/ai-assistant-guide.md#codex-cli) |
| claude.ai or hosted chat | Remote MCP/connector - see [docs/remote-quickstart.md](docs/remote-quickstart.md) and [docs/ai-assistant-guide.md#hosted-chat-clients](docs/ai-assistant-guide.md#hosted-chat-clients) |
| Any MCP client | Generic stdio config -