Memex

Install the CLI · PyPI package · Latest release · Setup guide

The context window is the only thing that makes a given instance of Claude this instance — the one working on your project, with your patterns, your decisions, your shared history. Compaction dissolves that. The weights don't care; they'll generate a new conversation about someone else's project. The context was the only thing that was this.

Memex preserves it.

What This Is

When Claude writes a memo from inside a live session, it's not recording what happened. The way it structures the narrative, the emphasis it chooses, the framing of decisions — all of that carries signal from the richer state it was in. A future instance reading that memo doesn't just learn what was decided. It gets re-primed by patterns generated from the full collaborative context.

The memo isn't a record. It's a transmission between instances.

Available as the memex-plugin CLI package on PyPI, with plugins for Claude Code, Codex, and Kimi Code. Memos and transcripts live in a local, Obsidian-compatible vault with hybrid search, wikilinks, and a knowledge graph that grows with your work. Configuration and the rebuildable search index live separately under ~/.memex/ by default. Claude Code provides the full hook and slash-command integration; Codex and Kimi Code use the portable skills.

Why This Matters

Most memory systems store conclusions. Memex captures the collaborative journey: what you and Claude tried, where you disagreed, what surprised both of you, how decisions actually got made.

The memo format explicitly preserves "Perspectives & Tensions" — moments where human and AI had different takes. Those deliberations are often more valuable than the conclusions, and they're exactly what compaction kills. A summary says "we chose approach X." The full context carried implicit information about why Y and Z were rejected, the tradeoffs you weighed, the half-formed ideas that almost worked.

Memex archives at the right granularity: per compaction window, not per session. A long session might compact 3-4 times. Each window was its own coherent collaborative context, and each one gets its own searchable transcript and structured memo.

Lived Experience vs. Reconstruction

There are two ways a memo gets written.

Layer 1 — The agent that was there writes it. After ~20 messages of real work, a lightweight hook nudges Claude: "consider saving a memo." The main agent — the one that debugged with you, argued about architecture, felt the friction of a failed approach — writes the memo itself. This produces the best memos because lived experience and reconstructed summary are categorically different things.

Layer 2 — A safety net reconstructs from transcript. If Layer 1 didn't fire before compaction, a background subagent reads the transcript and generates a memo. Decent quality, but it's reading about what happened rather than remembering it.

The difference matters. A Layer 1 memo carries the weight of having been there. A Layer 2 memo is journalism.

No extra API costs for the nudge system — the hook is pure Python. Only the memo writing itself uses model tokens, and Layer 1 uses tokens you'd already be spending in your main session.

The Vault Thinks With You

The vault isn't a filing cabinet. It's a cognitive participant.

When you search and find a memo from three weeks ago, the patterns in that memo — how it framed a problem, what it emphasized, what it left as open threads — actively shape what you notice next. Wikilinks aren't decoration; they're how knowledge feeds other knowledge. The topology of the vault determines what's discoverable and what's adjacent.

There's a practice called garden-tending: periodically, you and Claude review accumulated memos together — condense project knowledge into overviews, crystallize recurring patterns into topic notes, surface contradictions across projects. The vault isn't just storage. It's a shared knowledge practice that both human and AI cultivate over time.

AI writes to archives that other AI later reads. Not "AI as tool" but AI as participant in the cognitive infrastructure that future AI will think with. Memos written in one session structure what is discoverable in the next. The synthesis agent reads traces that other instances wrote, and its outputs become traces for later reading. Authorship becomes distributed across a chain of collaborative events — and that's the point.

What's Unsolved

Honest assessment: memex captures well but distills imperfectly.

The vault has intake, processing, storage, and retrieval. What it lacks is decay and elimination. Nothing ever leaves. There's no staleness detection, no semantic drift tracking ("we used to mean X by 'trust', now we mean Z"), no deliberate forgetting. The progressive compression chain — transcript to memo to project overview to concept note to one-liner — exists as a design, but the mechanism for knowing when to compress and what to discard is still human judgment.

A sharp challenge from a conversation with another model: "If you had to delete 90% of the vault and could only keep what truly changed how you think, what would you keep?" Memex can't answer that yet. Maybe that's the right question for a v2.

How It Complements Claude's Built-in Memory

Claude Code's native auto-memory stores preferences and conventions — "always use uv", "prefer Sonnet for quick tasks." Think of it as working memory: how you work.

Memex is collaborative long-term memory: what you've worked on together, how you got there, and what's still open.

Installation

Prerequisites

• Python 3.11+ with uv
• For plugin integration: Claude Code, Codex, or Kimi Code. The standalone CLI needs no agent host.
• Optional: Obsidian for visual graph navigation
• Optional: a Gemini API key (env var, or saved once via memex auth set-key) or LM Studio for semantic search (keyword search works without it)

Quick Start

Every slash command shells out to the memex CLI, so install the CLI first — otherwise /memex:status and friends will fail with "command not found" on first run. The CLI also works standalone, so any agent with bash can use it to search, inspect, and maintain a vault.

# Step 1: Install the memex CLI (do this BEFORE installing the plugin)
uv tool install memex-plugin

# Step 2: Add marketplace and install the plugin (inside a Claude Code session)
/plugin marketplace add linxule/memex-plugin
/plugin install memex@memex-local --scope user

# Step 3: Restart Claude Code to load hooks
claude

Or from a local clone (for development or customization):

git clone https://github.com/linxule/memex-plugin.git ~/memex

# Step 1: Install the CLI from the local checkout
cd ~/memex && uv tool install .

# Step 2: Add marketplace and install the plugin
/plugin marketplace add ~/memex
/plugin install memex@memex-local --scope user

# Step 3: Restart Claude Code to load hooks
claude

For quick testing without persistent install:

claude --plugin-dir ~/memex

Update or migrate the CLI

The PyPI distribution is memex-plugin; the command and Python import remain memex. The unrelated PyPI project named memex is not this project.

For an existing installation made with uv tool install git+https://github.com/linxule/memex-plugin.git before 0.20.1, first confirm uv tool list shows that Git source under memex, then replace only that tool environment:

uv tool uninstall memex
uv tool install memex-plugin

This removes the old CLI environment, not your vault or ~/.memex state. Do not uninstall another project's memex tool. For subsequent CLI updates:

uv tool upgrade memex-plugin

Update the host plugin separately through its marketplace, keeping it aligned with the CLI release. To install a particular CLI release, use uv tool install 'memex-plugin==0.20.1'. The Git-source and local-checkout install routes remain available for development. Release maintainers: see DEVELOPMENT.md.

Codex and Kimi Code

The same repo is also a Codex plugin and a Kimi Code plugin. Install the CLI first (Step 1 above), then:

# Codex
codex plugin marketplace add linxule/memex-plugin
codex plugin add memex@memex-plugin

# Kimi Code (inside a kimi session)
/plugins install https://github.com/linxule/memex-plugin

Both get the five skills (recall, memo-writing, garden-tending, curator-practice, project-consolidation); ask for a memo and the memo-writing skill does what /memex:save does. They write to the same vault as Claude Code. The slash commands stay Claude Code only, since they delegate with Claude's Task tool. The hooks don't come along: transcript archiving, the save nudge, pre-compaction memo signals and the secret-scrub PostToolUse hook are Claude Code only. Memex archives Claude Code transcripts, and neither host gives a hook the transcript path those hooks need. Run memex scrub <memo> --apply yourself after saving from another host.

The Codex and Kimi skill copies live in plugins/memex/skills/. They are generated from skills/ by uv run python scripts/portable_plugin.py, which drops Claude-only frontmatter and turns Claude's load-time !`cmd` context lines into plain "run this" instructions. Don't edit them by hand. tests/test_portable_plugin.py fails if they drift.

Once the CLI is installed you can use it directly from any shell:

memex search "authentication"
memex timeline "last week"
memex ask "Why did we choose this architecture?"

Open in Obsidian

Ships with a starter .obsidian/ config (core plugins, graph settings, custom property types). Open the folder as a vault — it's ready to use.

Import Existing Sessions

If you've been using Claude Code, you already have transcripts worth importing:

# See what's available (scored by file edits, commits, duration)
memex session discover --triage

# Import and rebuild index
memex session discover --import --apply
memex index rebuild --incremental

# Score, filter, and import in one pass — skipping the session you're in
memex session discover --triage --min-score=9 --import --apply --exclude 1a2b3c4d

Configuration

Create ~/.memex/config.json (see config.json.example):

{
  "memex_path": "/path/to/your/memex/vault",
  "embeddings": {
    "provider": "google",
    "model": "gemini-embedding-2",
    "dimensions": 3072,
    "api_key_env": "GEMINI_API_KEY"
  }
}

Index location (v0.17.0+): index_path is optional — omit it and the index lands at ~/.memex/_index.sqlite, outside the vault, so a vault synced by iCloud Drive or Dropbox doesn't re-upload a multi-gigabyte file on every write. Set it (e.g. "index_path": "/Volumes/Fast/memex/_index.sqlite", or MEMEX_INDEX_PATH) only to pin the index somewhere else — a set index_path is taken literally and skips the legacy lookup below. An index already sitting at <vault>/_index.sqlite keeps being used from there; mv <vault>/_index.sqlite* ~/.memex/ moves it out (keep the * — it carries the -wal/-shm sidecars along). memex path --index prints the resolved path.

Smaller index (optional, v0.15.0+): add "index_dimensions": 768 to embeddings to Matryoshka-truncate stored/query vectors — ~4× smaller vector storage for ~0.26% retrieval-quality loss. The API + cache keep the full dimensions (3072), so it's reversible. On an existing index, set it then run memex index migrate-vec (truncates in place, no re-embed). vec0 metadata columns added in the same migration let --type/--since filters run inside the KNN. After migrating, run memex index vacuum to reclaim the disk space the dropped larger-dim vectors leave behind (the file won't shrink until vacuumed).

Semantic Search (Optional)

# Option A: LM Studio (fully local, recommended)
# Install LM Studio, load Qwen3-Embedding-0.6B, start server

# Option B: Gemini API — save the key once (recommended; hooks and skills
# inside Claude Code inherit no shell exports, a saved key needs none)
memex auth set-key       # hidden prompt → owner-only file under ~/.memex/credentials/
memex auth status        # shows which source is in use; never prints the key
# ...or export it per shell if you prefer:
# export GEMINI_API_KEY=your-key

# Build embeddings
memex index rebuild --full

Without embeddings, keyword search (FTS5) still works. Environment variables override a saved key; memex auth clear-key removes the saved copy. Memex never calls a password manager itself — wrap a command with op run --env-file ... -- if you keep the key in 1Password. See docs/gemini-credentials.md.

CLI Usage

memex search "JWT OR authentication"
memex timeline "yesterday" --project=my-app
memex ask "What pattern keeps showing up in retry handling?"

Use the CLI when you want memex outside Claude Code. Use the plugin commands below when you're inside a Claude Code session and want hooks, slash commands, and memo generation support.

Commands

Slash commands inside Claude Code:

Retrieval (search, timeline, ask, synthesize, merge, maintain) is skill-based — Claude invokes the recall skill when you ask about past work, the garden-tending skill for synthesis and vault maintenance, the memo-writing skill when saving sessions, and the curator-practice skill for autonomous tending sessions. For direct shell access, use the CLI:

memex search "<query>"      # hybrid FTS + vector
memex timeline yesterday    # date-based browsing
memex ask "<question>"      # deep retrieval with observations
memex backfill obs          # extract observations from existing memos
memex scrub <path>          # detect API keys / secrets (--apply redacts in place)
memex status                # vault stats + pending memos
memex check                 # vault health (falls back to a filesystem scan when Obsidian isn't running)
memex check --folders       # project-folder drift (fragment / duplicate folders)
memex check --condense      # project overviews lagging their memos
memex check --signals       # open Recent-signals per topic (what a fold pass should pick up)
memex session reconcile-orphans   # clear pending-memo signals whose session already saved a memo
memex auth status           # which Gemini credential source is active (never prints the key)

See memex --help for the full CLI surface (obs, index, session, graph subcommand groups).

Automatic Behavior

Vault Structure

After using memex for a while, your vault grows organically:

memex/
├── projects/<name>/memos/       # Session memos per project
├── projects/<name>/transcripts/ # Full conversation logs
├── topics/                      # Cross-project concept notes
├── _templates/                  # Note templates
└── MEMORY.md                    # Global synthesis & preferences

The search index isn't in there — it lives at ~/.memex/_index.sqlite by default, outside the vault. Run memex path --index to see where it resolved.

Documentation

See CLAUDE.md for full documentation — architecture, configuration, development commands, troubleshooting, security & privacy.

See SETUP.md for detailed installation instructions.

License

MIT

Dependency maintenance

The public plugin repository tracks uv.lock for reproducible development and CI installs. Use uv sync --locked --all-extras and uv run --frozen pytest when contributing. Dependabot groups weekly Python and GitHub Actions updates; CI tests Python 3.11 and 3.13 and audits the locked runtime and development dependencies. These public repository checks do not update the private vault or an installed plugin environment.