memex

<!-- mcp-name: io.github.dioniipereyraa/memex -->

# Memex

[![CI](https://github.com/dioniipereyraa/memex/actions/workflows/ci.yml/badge.svg)](https://github.com/dioniipereyraa/memex/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)

**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.2.3` on PyPI. Phases 0 to 4 and 6 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), and Claude Code / terminal ingestion with secret redaction and automatic sync.

![Memex recalling a claude.ai chat from Claude Code](docs/screenshots/demo.gif)

*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.*

## 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 SSE/HTTP] ──→ Claude.ai (coming soon)
```

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

## Installation

Memex is a Python package. You do not need to install Python yourself: the
installer below uses [uv](https://docs.astral.sh/uv/), which downloads the
right Python (3.13) and all dependencies into a local environment. The only
thing you need beforehand is [git](https://git-scm.com/downloads).

Embeddings work **out of the box**: by default Memex uses
[fastembed](https://github.com/qdrant/fastembed), which downloads a quantized
130 MB model the first time you ingest. No Ollama, no API key, no extra setup.
(Ollama is optional, see [Embeddings backend](#embeddings-backend) below.)

> Note: a PyPI install gives you the CLI and the MCP servers, but the
> live-capture Chrome extension, the autostart scripts, and the
> launchd/systemd templates only come with the repo, so installing from
> source (below) is still the recommended path.

### macOS / Linux

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

```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](https://git-scm.com/downloads) first.

### Manual (any OS, if you prefer explicit steps)

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

## First run

```bash
# 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.)

## Embeddings backend

Default is fastembed (zero-config). To route through a local Ollama instead
(e.g. you already run it for other models):

```bash
export MEMEX_EMBED_BACKEND=ollama
ollama pull nomic-embed-text          # install Ollama first: https://ollama.com/download
```

On Windows, install Ollama from [ollama.com/download](https://ollama.com/download)
before setting `MEMEX_EMBED_BACKEND=ollama`. This is optional; fastembed needs
none of it.

## Diagnostics

Run `memex doctor` any time something is not working. It checks Python version, database, embedder, live-capture server, summarizer config, registered repos, and indexed corpus. Reports OK / WARN / FAIL per check.

## MCP server tools (v1)

- `search_chats(query, limit=5, source?, mode="hybrid", repo?)` searches the corpus. Modes: `hybrid` (default, combines vector search + FTS5 BM25 via Reciprocal Rank Fusion), `semantic` (vectors only), `lexical` (FTS5 only, ideal for proper nouns or exact terms). `source` filters by origin (`conversations`, `design_chat`, `memory`). `repo` boosts results associated to a registered repo (see "Repo associations" below). Deduplicated per conversation.
- `get_chat(uuid, messages_limit=10, messages_offset=0)` fetches a conversation with its messages, paginated. `raw_content` is omitted; each message is truncated to 1500 chars to stay inside the client's token budget (worst-case response ~17k chars). Long chats are paginated with `messages_offset`; max `messages_limit` is 100.
- `list_recent_chats(limit=10, source?)` lists the latest chats ordered by last update.
- `find_related(context, limit=5, repo?)` takes free-form text (a paragraph, a file contents, the current discussion) and returns chats that are semantically related. Pure vector search, no FTS, capped at 4000 input chars. Useful when you want "more like this" without typing a keyword query.

Search is also reachable from the CLI with `memex search "query" --mode {hybrid|semantic|lexical}`. For databases created before the hybrid FTS5 work, run `memex reindex-fts` once to populate the lexical index.

## Wiring it into Claude Code

Once your local database is populated (`memex ingest`), start the MCP server with `uv run memex-mcp`. For Claude Code to discover it automatically, add a `.mcp.json` file at the root of your project (or a user-level server in `~/.claude.json`):

```json
{
  "mcpServers": {
    "memex": {
      "command": "uv",
      "args": ["run", "memex-mcp"],
      "cwd": "/absolute/path/to/the/memex/repo"
    }
  }
}
```

Set `cwd` to the absolute path where you cloned Memex (where `pyproject.toml` lives). Restart Claude Code and the tools `search_chats`, `get_chat`, `list_recent_chats` will show up in the session.

The same searches are also available from the CLI via `uv run memex search "..."` if you prefer them outside Claude Code.

## Connecting from claude.ai (remote MCP, Phase 4)

`memex serve-remote` exposes the same 4 tools as a [custom connector](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp) for claude.ai. One connector works across claude.ai web, Claude Desktop, and the mobile apps: the connection is brokered by your Claude account and always originates from Anthropic's cloud, never from your device. That has two consequences:

1. The server must be reachable on a **public HTTPS URL** (a hostname with a public IPv4 `A` record; `localhost` and private IPs are rejected by design). The intended setup is a tunnel that terminates TLS and proxies to Memex on loopback.
2. Auth is either *none* or *full OAuth 2.0* (claude.ai has no field to paste a token). Memex uses OAuth backed by a GitHub OAuth App, restricted to an allow-list of GitHub usernames: anyone else who completes the OAuth dance still gets a 401 on every request. Your machine must be on (and the tunnel up) for the connector to respond.

### 1. Publish a URL with Tailscale Funnel

Install [Tailscale](https://tailscale.com/download), log in, then:

```bash
tailscale funnel --bg 8377
```

This prints your public URL, e.g. `https://my-mac.my-tailnet.ts.net`, TLS included. Any other tunnel works the same way (ngrok, Cloudflare Tunnel); Memex only needs the resulting `https://` URL.

### 2. Create a GitHub OAuth App

At [github.com/settings/developers](https://github.com/settings/developers) > OAuth Apps > New OAuth App:

- Homepage URL: your funnel URL.
- Authorization callback URL: `<funnel URL>/auth/callback`.

Copy the Client ID and generate a Client Secret.

### 3. Configure and run

In `.env` (see `.env.example`):

```bash
MEMEX_REMOTE_BASE_URL=https://my-mac.my-tailnet.ts.net
MEMEX_GITHUB_CLIENT_ID=Iv1.xxxxxxxxxxxx
MEMEX_GITHUB_CLIENT_SECRET=xxxxxxxxxxxxxxxxxxxx
MEMEX_REMOTE_ALLOWED_GITHUB_LOGINS=your-github-username
```

```bash
uv run memex serve-remote   # listens on 127.0.0.1:8377, endpoint at /mcp
```

The server refuses to start with incomplete config (no insecure defaults: an empty allow-list would expose yo