Memex Plugin: Persistent Research Memory

Without memory, every AI session starts the relationship over.

Memex Plugin solves a fundamental problem in sustained human-AI research collaboration: when your session ends, the context disappears. The insights, the decision rationale, the tensions you worked through: gone. Memex preserves it.

Current source version: 0.16.3

Why it matters

Research projects span weeks or months. Each session with Claude builds understanding: which papers matter, what theoretical tensions you're tracking, why you chose one methodology over another. Without persistent memory, every new session starts from scratch.

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

How it works

Two-layer memo system

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

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.

As of v0.15.9, memex check also treats projects/<slug>/_project.md overviews as valid targets for bare [[project-slug]] links. That keeps cross-project references from inflating the ghost-node queue while still surfacing folder fragments that lack a real project overview.

As of v0.15.10, memex check ends with a curator-artifact freshness section when the vault has a curator dashboard. It compares the dashboard and curator log with the newest non-archived topic edit, warning when either trails active topic work by more than seven days. Quiet vaults do not generate wall-clock nagging, and the same result is available under curator_artifacts in JSON output.

Automatic hooks

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

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

# 1. Install the CLI package
uv tool install git+https://github.com/linxule/memex-plugin.git

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

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.

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
export GEMINI_API_KEY=your-key

# Build embeddings
memex index rebuild --full

Part of Research Memex

Memex Plugin works alongside:

• Interpretive Orchestration Plugin — Persistent memory across stages of qualitative analysis
• Carrel: The environment Memex lives inside. Carrel sets the desk; Memex remembers what happened on it.
• Obsidian Setup Guide: Your knowledge management system where memos live.
• Claude Code Setup Guide: The research environment where Memex operates.