Memex

Memex

Your Claude.ai chats and your Claude Code sessions live in two worlds that never talk. Memex makes them one memory you can search from both.

Local-first MCP server that indexes your Claude.ai chat history and your local Claude Code / terminal sessions, and exposes them to Claude Code (stdio) and Claude.ai (remote MCP connector).

Status: alpha, 0.3.1 on PyPI. Phases 0 to 7 closed, security-audited (plus four adversarial red-team rounds). Shipped: hybrid search, live capture, auto-summaries, chat ↔ repo association, the Claude.ai remote connector (GitHub OAuth), Claude Code / terminal ingestion with secret redaction, one-command setup, cross-platform autostart, and one-click claude.ai history backfill.

*End-to-end demo: from Claude Code, you ask about something you discussed on claude.ai. Memex searches your chat history (search_chats) and Claude answers from the real conversation. No copy-paste, no manual context handoff.*

Install

One command installs uv + Memex and runs memex setup (registers the MCP server, installs the always-on capture service, indexes your local sessions, prints the pairing token):

# macOS / Linux

curl -LsSf https://raw.githubusercontent.com/dioniipereyraa/memex/main/scripts/install-pypi.sh | sh

# Windows (PowerShell)

powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/dioniipereyraa/memex/main/scripts/install-pypi.ps1 | iex"

Then the one browser step a terminal cannot do: install the Chrome extension, paste the token it printed, and click "Backfill claude.ai history". Other paths (pipx, uv tool install, from source) are under Installation.

The problem

Brainstorming and planning happen in Claude.ai. Execution happens in Claude Code. The two worlds do not talk to each other: Claude Code cannot read a chat of yours from Claude.ai, not even the one that originated the task it is currently working on. The memory Anthropic shipped on Claude.ai (March 2026) is curated, not full history, and lives isolated inside Claude.ai.

Memex fills that gap: runs locally, indexes the entire corpus of your chats, and exposes them as MCP tools so Claude can search and pull past context whenever it needs to.

How it works

[Claude.ai]

↓ (official JSON export / Chrome ext) [Ingestor] → [SQLite + sqlite-vec] → [local embeddings (fastembed / Ollama)] ↓ [core: storage + retrieval] ↓ [MCP stdio] ───→ Claude Code, Claude Desktop [MCP Streamable HTTP] ─→ Claude.ai connector

Design: pure core (storage, ingest, embeddings, retrieval) decoupled from transport. The same engine serves both stdio and remote MCP without a rewrite.

Installation

Quick install (one command)

Installs uv if needed (it brings the right Python), installs Memex from PyPI, and runs memex setup to wire it into Claude Code (MCP server + always-on capture service + local session indexing + the pairing token). No git clone required.

# macOS / Linux

curl -LsSf https://raw.githubusercontent.com/dioniipereyraa/memex/main/scripts/install-pypi.sh | sh

# Windows (PowerShell)

powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/dioniipereyraa/memex/main/scripts/install-pypi.ps1 | iex"

The only step a terminal cannot do is the browser one: install the Chrome extension, paste the token the installer prints, and click "Backfill claude.ai history" to import your history. Embeddings work out of the box (a quantized 130 MB fastembed model downloads on first ingest; no Ollama, no API key).

A plain pipx install memex-chats (or uv tool install memex-chats) followed

by memex setup does the same thing in two steps. The autostart service is

generated for the wheel install too (launchd / systemd / a logon Scheduled

Task), so no clone is needed for it.

From source (for development)

Clone the repo to get an editable install plus the extension source and service templates. You need git; the script installs uv and the pinned Python for you.

macOS / Linux

git clone https://github.com/dioniipereyraa/memex

cd memex ./scripts/install.sh

install.sh installs uv if you do not have it, runs uv sync, and verifies the install with memex doctor. That is the whole setup.

Windows (PowerShell)

git clone https://github.com/dioniipereyraa/memex

cd memex powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1

Same three steps as the macOS script (install uv, sync, verify). If git is not installed, get it from git-scm.com first.

Manual (any OS, if you prefer explicit steps)

# 1. Install uv (skip if you already have it):

macOS/Linux: curl -LsSf https://astral.sh/uv/install.sh | sh

Windows: powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

git clone https://github.com/dioniipereyraa/memex cd memex uv sync # installs Python 3.13 + dependencies into .venv uv run memex doctor # verify

Upgrading (already have memex)

Upgrade with the same tool that installed it, or the new version will not land on your PATH. A previous install owns the memex executable, so installing again with a different manager fails with "Executables already exist" and memex keeps running the old version. (This is the usual reason memex sync seems to "not exist" after an upgrade: an old pipx-owned memex shadowed a newer uv tool install.)

# 1. Find which tool owns it:

which memex # macOS / Linux Get-Command memex # Windows (PowerShell)

2. Upgrade with that tool:

pipx upgrade memex-chats # if pipx owns it uv tool upgrade memex-chats # if uv owns it

If you want to switch managers, uninstall the old one first (pipx uninstall memex-chats or uv tool uninstall memex-chats), then reinstall. After upgrading, memex --version shows the new version and memex doctor should pass.

Multi-device (optional)

To make Claude one memory across several machines, install Tailscale first (so each device has a stable private address), then opt in once per device:

memex setup --sync     # opt-in, persisted: the always-on service is sync-reachable

It prints the single memex sync connect ... line to run on your other devices. The choice is saved, so the service stays sync-reachable across reboots without re-running anything. Full flow, security model, and the manual one-shot alternative are in Syncing across your devices.

For a dual-boot machine (Linux and Windows that are never on at the same time), use file-based sync instead: memex setup --sync-dir on each OS, pointed at the same folder. No Tailscale, no two devices online at once. See Dual-boot or never-online-together.

First run

The fast path is one command:

uv run memex setup

memex setup wires everything end to end and is safe to re-run: it registers the MCP server with Claude Code (claude mcp add), installs the always-on live-capture service (launchd on macOS, systemd on Linux, a Scheduled Task on Windows), indexes your local Claude Code sessions, and prints the access token to paste into the Chrome extension. Each step degrades to a warning instead of aborting the rest. Flags: --no-mcp, --no-autostart, --no-ingest, --remote (also install the claude.ai connector agent), -y (no prompt).

After that, the only manual step left is installing the Chrome extension and pasting the token, so new chats are captured as you go.

Manual steps (if you prefer to run them yourself)

# 1. Request your official Claude.ai export (Settings → Privacy → Export data),

then ingest it (first run downloads the embedding model, ~30s):

uv run memex ingest /path/to/your-export.zip

2. Optionally index your local Claude Code / terminal sessions:

uv run memex ingest-claude-code

3. Search, or wire it into Claude Code (see "Wiring it into Claude Code"):

uv run memex search "your query" -n 5 uv run memex stats

(If you installed with a script, the commands above work as written. If you installed the published PyPI package instead, drop the uv run prefix.)

Where your data lives. From a cloned repo, the database and exports stay

in /data. From a uvx/pip install, they go to your OS data

directory (~/Library/Application Support/memex on macOS,

%LOCALAPPDATA%\memex on Windows, ~/.local/share/memex elsewhere). Override

with MEMEX_DB_PATH / MEMEX_EXPORTS_DIR. memex doctor prints the resolved

path.

Using Memex (after setup)

Once memex setup finishes, nothing else needs launching: the capture server and the indexers run in the background. You use Memex three ways.

1. From Claude Code (the main way). Setup registers the MCP server, so Claude Code can search your whole history and keep it fresh through these tools:

Just ask Claude Code naturally ("what did we decide about X in my claude.ai chats?", "index this session", "sync this to my other devices") and it calls these. index_terminal_sessions and sync_now are local-only (never exposed to the remote claude.ai connector). Note sync_now sends what is already indexed, so to include the session you are in, ask Claude to index_terminal_sessions first. To have context injected automatically at the start of a session, add the optional SessionStart hook.

2. From the terminal. memex search "...", memex stats, memex doctor, memex token (re-print the extension pairing token), memex --version.

3. Capture (automatic, you run nothing). The Chrome extension indexes a claude.ai chat as you open or reload it (and its "Backfill" button imports your old history once); your Claude Code sessions are indexed when a session ends, plus a 15-minute backstop.

How fresh is the data (real-time)?

Same-machine is essentially real-time. Cross-device is not a live relay (it is peer-to-peer with no cloud): paired devices auto-reconcile every 15 minutes while