# Memex Plugin: Persistent Research Memory
URL: https://research-memex.org/docs/toolkit/memex-plugin
Description: A Claude Code plugin that preserves collaborative AI-human work across sessions: persistent, searchable, interconnected memos in an Obsidian vault.
*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](https://github.com/linxule/memex-plugin/releases)
## Why it matters [#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 [#how-it-complements-claudes-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.
| | Auto-memory (built-in) | Memex |
| ----------- | ----------------------------- | ---------------------------------------------- |
| Scope | Session-scoped preferences | Cross-session archive |
| Captures | Conventions, patterns | Full transcripts + structured memos |
| Granularity | Key-value pairs | Per-compaction-window transcripts |
| Search | Exact match | Hybrid FTS + semantic |
| Answers | "What does this user prefer?" | "Why did we choose this approach 3 weeks ago?" |
## How it works [#how-it-works]
### Two-layer memo system [#two-layer-memo-system]
The active Claude instance writes memos after substantial collaborative work (\~20 messages). These memos carry the weight of having been there: the nuanced understanding that comes from working through a problem together.
Layer 1 memos capture:
* Important decisions and their context
* Tensions between competing approaches
* Insights that emerged through dialogue
* What was tried and why it worked (or didn't)
If Layer 1 doesn't trigger before context compaction, a background agent reconstructs from transcripts. Layer 2 memos are journalism: accurate but missing the lived experience.
This ensures nothing is lost, even in long sessions where compaction happens before a natural memo point. The fallback and retry prompts pin memo-generation subagents to `model='sonnet'`, so memo writing stays on a capable but cheaper model even when the main session is heavier.
### Obsidian vault integration [#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 [#commands]
| Command | What it does |
| --------------------- | ------------------------------ |
| `/memex:save [title]` | Save current context as a memo |
| `/memex:status` | Show vault statistics |
| `/memex:open` | Open vault in Finder/Obsidian |
Retrieval and maintenance now live in skills plus the portable CLI, rather than extra slash commands:
| Surface | What it does |
| -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `recall` skill | Uses `memex search`, `memex timeline`, and `memex ask` to retrieve past decisions into the current conversation |
| `garden-tending` skill | Runs vault health checks, link repair, and crystallization readiness work |
| `memo-writing` skill | Writes substantial session memos and extracts observations |
| `curator-practice` skill | Periodic vault review and topic curation |
| `memex search ""` | Hybrid FTS + optional vector search |
| `memex timeline yesterday` | Date-based browsing |
| `memex ask ""` | Deep retrieval over memos and extracted observations |
| `memex backfill obs --stdin (--replace\|--append) --doc-path ` | Store extracted observations with an explicit write mode |
| `memex status` / `memex check` | Vault statistics and crystallization-readiness checks |
| `memex check --folders` | Detect project-folder drift and duplicate/split project folders |
| `memex check --validate` | Lint vault frontmatter for merged keys, missing titles, dangling delimiters, and missing frontmatter |
| `memex scrub ` | Detect secrets and optionally redact them with `--apply` |
| `memex index vacuum` | Reclaim index free pages after vector migrations |
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//_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 [#automatic-hooks]
The plugin hooks into Claude Code's session lifecycle automatically:
| Hook | When | What |
| ------------------ | ----------------- | --------------------------------------------------- |
| `SessionStart` | New session | Loads project context, recent memos, open threads |
| `UserPromptSubmit` | Each message | Tracks activity, nudges to save after \~20 messages |
| `SessionEnd` | Session closes | Archives transcript |
| `PreCompact` | Before compaction | Writes signal file for safety-net memo generation |
## Host support [#host-support]
The vault itself is just an Obsidian folder of markdown files, readable by anything that reads markdown.
## Research workflow example [#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 [#install]
### Prerequisites [#prerequisites]
* [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code)
* Python 3.11+ with [uv](https://docs.astral.sh/uv/)
* [Obsidian](https://obsidian.md/) for visual graph navigation
* LM Studio or `GEMINI_API_KEY` for semantic search (keyword search works without it)
### Quick start [#quick-start]
```text
# 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:
```text
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 [#configuration]
Create `~/.memex/config.json` to customize your vault location:
```json
{
"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 [#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:
```bash
# 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) [#semantic-search-optional]
Without embeddings, keyword search (FTS5) works out of the box. For semantic search:
```bash
# 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 [#part-of-research-memex]
Memex Plugin works alongside:
* [Interpretive Orchestration Plugin](/docs/toolkit/interpretive-orchestration-plugin) — Persistent memory across stages of qualitative analysis
* [Carrel](/docs/toolkit/carrel): The environment Memex lives inside. Carrel sets the desk; Memex remembers what happened on it.
* [Obsidian Setup Guide](/docs/implementation/foundational-setup/obsidian-setup-guide): Your knowledge management system where memos live.
* [Claude Code Setup Guide](/docs/implementation/agentic-ai-tools/claude-code-setup-guide): The research environment where Memex operates.