Memex: Persistent research memory

Without memory, every AI session starts the relationship over.

Memex preserves decisions, disagreements, and working context in an Obsidian-compatible vault. Use its standalone CLI or a plugin for Claude Code, Codex, or Kimi Code.

The hosts share the same vault, but not the same automation. Claude Code provides lifecycle hooks and slash commands. Codex and Kimi Code provide portable skills for recall, memo writing, and curation. Their plugins do not run Claude-only hooks, including automatic transcript archiving and secret scrubbing.

Current release: 0.20.3 (opens in a new tab)

Why it matters

Research projects span weeks or months. Sessions build context about papers, theoretical tensions, and methodological choices. Memex makes saved records available to later sessions, rather than relying on the current conversation alone.

Memex captures the collaborative journey:

• Decisions and rationale: not just what you decided, but why
• Perspectives and tensions: disagreements and tradeoffs, not just conclusions
• Evolving understanding: how your thinking developed across sessions

How it complements your host's memory

Your host's own memory holds how you work: preferences and conventions. Memex holds what you worked on together: the decision, the alternatives you set aside, and why.

Claude Code's integration also archives transcripts around compaction. In Codex and Kimi Code, use the portable skills to save memos explicitly. Neither route guarantees a complete record of every conversation.

How it works

Two-layer memo system

This automatic capture system belongs to the Claude Code integration. The portable plugins use the CLI and skills without these lifecycle hooks.

Obsidian vault integration

The vault organizes memos with:

• Project folders: memos grouped by research project
• Wikilinks: connections across sessions and projects
• Hybrid search: full-text plus optional semantic search
• Knowledge graphs: visualization of how your research connects

Commands

The slash commands below are specific to Claude Code. Codex and Kimi Code use skills and the same standalone CLI.

Retrieval and maintenance now live in skills plus the portable CLI, rather than extra slash commands:

Observation writes now require an explicit mode. --replace deletes the memo's existing observations before storing the submitted set, so send the complete set in one call. Use --append only for a deliberate addition. The result reports replaced and skipped rows, and observation deletion removes the search, vector, and topic rows that mirror it.

memex check recognizes project-overview links and checks curator-artifact freshness against active topic edits, not elapsed time alone. JSON output includes the same curator_artifacts result.

Current 0.20.x release line

The PyPI package is now memex-plugin (opens in a new tab); the executable and Python import remain memex. This release line adds curation-backlog checks, stamp-exact orphan reconciliation, portable Codex/Kimi packaging, and the consolidation-arrival signal described above. Installation and migration steps follow below.

Automatic hooks

The plugin hooks into Claude Code's session lifecycle automatically:

The scrub hook runs after the write and does not block writes if scrubbing fails. It does not cover every file or guarantee that every secret is detected.

Host support

The vault itself is just an Obsidian folder of markdown files, readable by anything that reads markdown.

Research workflow example

Week 1: You and Claude analyze 20 papers and develop an initial coding framework. Memex captures the framework rationale and which papers mattered most.

Week 3: You return after a break. Ask Claude to recall the coding framework, or run memex search "coding framework" directly: not just the framework itself, but why you made each decision.

Week 5: You're writing up methodology. The garden-tending and curator-practice skills, plus memex ask, surface how your analytical approach evolved across sessions. This gives you the reflexivity narrative for your paper.

Install

Prerequisites

Quick start with Claude Code

# 1. Install the published CLI package
uv tool install memex-plugin

# 2. Inside Claude Code, add the marketplace and install the plugin
/plugin marketplace add linxule/memex-plugin
/plugin install memex@memex-local --scope user

# 3. Restart Claude Code to load hooks
claude

Despite its name, memex-local is also the marketplace identifier declared by the public GitHub repository's .claude-plugin/marketplace.json; it is not limited to local-clone installs. The marketplace source distinguishes the two paths: linxule/memex-plugin uses the public repository, while ~/memex uses your checkout. Both sources install memex@memex-local.

For an existing Git-source CLI installed before 0.20.1, confirm it with uv tool list, then replace only that tool environment:

uv tool uninstall memex
uv tool install memex-plugin

For subsequent updates, use uv tool upgrade memex-plugin. Keep the host plugin update separate, and do not uninstall an unrelated tool named memex.

For a local clone or unreleased changes:

git clone https://github.com/linxule/memex-plugin.git ~/memex
cd ~/memex
uv tool install .
/plugin marketplace add ~/memex
/plugin install memex@memex-local --scope user

Codex and Kimi Code

After installing the CLI with uv tool install memex-plugin, install the portable plugin in the host. The CLI package alone does not install these skills.

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

For Kimi Code, run /plugins install https://github.com/linxule/memex-plugin inside a Kimi session. Both hosts share the vault; the Claude-only hooks listed above do not run there, so nothing scrubs a memo for you. Run memex scrub <memo> to inspect a saved memo and add --apply to redact detected patterns. Review the result before sharing it. The upstream portable-plugin instructions (opens in a new tab) describe the host differences.

Configuration

Create ~/.memex/config.json to customize your vault location:

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

See config.json.example in the plugin repo for all available options.

For smaller vector indexes, v0.15+ can Matryoshka-truncate stored and query vectors by adding "index_dimensions": 768 under embeddings. Existing indexes can migrate with memex index migrate-vec; run memex index vacuum afterward to reclaim disk space.

v0.15+ also moved metadata filters such as --type and --since into the vec0 query path, so semantic search does less post-filtering work.

As of v0.17.0, the default SQLite index lives at ~/.memex/_index.sqlite, outside the vault, so vault syncs do not copy the index or its WAL sidecars. Set "index_path" or MEMEX_INDEX_PATH to pin another location; an existing <vault>/_index.sqlite remains a legacy fallback. Run memex path --index to see the resolved path.

The v0.18 maintenance releases repair keyword-only indexing and search: rebuilding without an embedding key preserves stored observations, removes stale index entries, and leaves missing vectors available for a later embedding pass. Index writers coordinate through a shared lock.

Upgrading observations from 0.18

Version 0.19 stores observations beside their documents as <doc>.obs.jsonl sidecars, so the vault can carry them between machines while each machine keeps its own SQLite index. Existing observations stored only in an index need a one-time memex obs export-sidecars pass; it previews changes by default and refuses to overwrite differing sidecars unless explicitly forced. Review that preview and the 0.19 changelog (opens in a new tab) before applying the export with --apply on the machine holding the authoritative index. Sync or commit the sidecars with their memos; do not export a stale second-machine index over newer vault data.

Index rebuilds ingest changed sidecars; memex obs ingest-sidecars can ingest them separately, and memex obs sidecars reports their health. The added index tables are created automatically. Version 0.19.1 adds dependency maintenance without another schema or vault migration.

Import existing sessions

If you've been using Claude Code already, you have transcripts worth importing. The discover_sessions.py tool scores existing sessions by file edits, commits, and duration to find the ones with real collaborative work:

# See what's available
memex session discover --triage

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

# Score, filter, and import in one pass; exclude a live session by id
memex session discover --triage --min-score=9 --import --apply --exclude 1a2b3c4d

Versions 0.16.2–0.16.3 repaired this import path without changing the basic workflow. Sessions opened from hidden directories or worktrees now resolve to the real project rather than a fragment folder; project-name sanitizing is stable across repeated writes; --triage now works when combined with --import; and --exclude no longer corrupts JSON output. The transcript converter now ships inside the installed package and uses the real shared helpers, so imports log consistently and cannot revive the older naming bugs through fallback code.

Semantic search (optional)

Without embeddings, keyword search (FTS5) works out of the box. For semantic search:

# Option A: LM Studio (fully local, recommended)
# Install LM Studio, load an embedding model, start server

# Option B: Gemini API - save once for later CLI and hook runs
memex auth set-key  # hidden interactive prompt
memex auth status  # reports the source, never the key

# Build embeddings
memex index rebuild --full

memex auth set-key stores an unencrypted, owner-only file under ~/.memex/credentials/. An exported GEMINI_API_KEY overrides the saved copy; memex auth clear-key removes that copy. Saving a key or checking its source does not validate it with Google. Memex never opens a password manager on its own.

Part of Research Memex

Memex Plugin works alongside:

• Interpretive Orchestration Plugin — Persistent memory across stages of qualitative analysis
• Carrel: Optional research-environment setup for Claude Code. Install Memex separately.
• Obsidian Setup Guide: Your knowledge management system where memos live.
• Claude Code Setup Guide: Setup for the host that provides Memex's automatic lifecycle hooks.