memex — claude-memory-explorer

Browse, dedupe, lint, and promote your Claude Code auto-memory across every project. Every mutation is journaled and reversible by memex undo. Closes the gap anthropics/claude-code#58840 describes.

Claude Code stores per-project memory at ~/.claude/projects/<slug>/memory/. Every project is a silo. After a few months of real use:

• The same user_* / feedback_* rule ends up in 12 different projects
• Stale project facts keep loading into every session
• user/feedback memories that should live in ~/.claude/CLAUDE.md don't
• MEMORY.md files quietly cross the documented 200-line / 25KB cutoff and the tail is dropped at load time
• Malformed YAML in a single memory file (which Claude itself sometimes writes) makes that memory invisible — and there's no warning

memex is a CLI, TUI, and MCP server that finds and fixes all of that. Install once as a Claude Code plugin and Claude can curate its own memory inside a normal session.

What's inside

memex list       List memories across all projects
memex doctor     One-shot health report (run weekly)
memex lint       Structural problems (CI-friendly)
memex dedupe     Find duplicate memories across projects
memex merge      Collapse a duplicate cluster down to its representative
memex promote    Move a memory (or whole cluster) into ~/.claude/CLAUDE.md
memex undo       Reverse the most recent mutation (any of the above)
memex tui        Interactive three-pane browser
memex mcp        Run as an MCP server for Claude Code plugins

Every mutation goes through a journaled Plan → applyPlan layer at ~/.claude/.memex/log/. Everything is undoable. memex undo reverses the most recent plan; a second undo is redo.

Install

As a Claude Code plugin (recommended)

/plugin install claude-memory-explorer@community

If the community catalog hasn't synced this plugin yet (sync is ~once a day), install directly from this repo instead:

/plugin marketplace add hseinmoussa/claude-memory-explorer
/plugin install claude-memory-explorer

Once installed, ask Claude:

"Clean up my memory."

…and the bundled curate-memory skill takes over. Claude calls doctor, shows you the findings, generates Plans for the suggested fixes, asks for your OK, then applies them via apply_plan (all journaled, all undoable).

As a standalone CLI

npm install -g claude-memory-explorer

memex doctor                     # health snapshot
memex lint                       # structural issues
memex dedupe                     # cross-project duplicates
memex tui                        # interactive browser

Or one-shot via npx:

npx claude-memory-explorer doctor

The killer demo

Three projects, same user-preference memory written into each:

~/.claude/projects/-Users-foo-Desktop-vida/memory/user_terse.md
~/.claude/projects/-Users-foo-Desktop-app/memory/user_terse.md
~/.claude/projects/-Users-foo-Desktop-bot/memory/user_terse.md

memex dedupe finds the cluster and flags it as a promote-to-global candidate:

c1  type=user  count=3  distinctProjects=3  [promote-to-global candidate]
  ★ -Users-foo-Desktop-bot/user_terse.md
    -Users-foo-Desktop-vida/user_terse.md
    -Users-foo-Desktop-app/user_terse.md

memex promote --cluster c1 --apply then:

1. Writes the body into ~/.claude/CLAUDE.md under a managed marker block:

   <!-- memex:start:user_terse -->
   ## Be terse
   The user prefers terse, direct answers.
   <!-- memex:end:user_terse -->

2. Deletes the 3 source files
3. Cleans the affected MEMORY.md indexes (removes pointer lines, leaves unrelated entries intact)

Result: one block in ~/.claude/CLAUDE.md (which Claude loads in every session of every project) replaces three siloed copies.

Run memex undo and everything is restored byte-for-byte.

How memex thinks

| Concept | Description | |---|---| | Memory | A markdown file at ~/.claude/projects/<slug>/memory/<topic>.md with YAML frontmatter (type: user\|feedback\|project\|reference) | | Index | MEMORY.md in each memory dir. Documented as a list of pointer-style links to topic files; in practice Claude writes inline content too. memex tolerates both. | | Worktree collapse | <slug>--claude-worktrees-* slugs collapse to the base slug when counting distinct projects, so worktrees of one repo don't inflate the duplicate count | | Promotion candidate | A cluster where distinctProjects ≥ 3 AND type ∈ {user, feedback}. Project- and reference-typed memories stay project-scoped. | | Managed block | <!-- memex:start:<slug> --> / <!-- memex:end:<slug> --> markers in ~/.claude/CLAUDE.md. memex never touches content outside its own markers. | | Plan | A JSON-serializable list of write / delete / ensure-dir ops. Every mutation builds a plan, then applyPlan is the single writer. | | Journal | ~/.claude/.memex/log/<id>.json. One entry per applied plan, with inverse ops captured at apply time. memex undo walks the journal. |

MCP server tools

When installed as a plugin, the MCP server exposes 11 tools:

| Tool | Type | Description | |---|---|---| | list_memories | read | All memories, filterable by type/project | | find_duplicates | read | Cross-project clusters | | lint | read | Structural issues | | doctor | read | Aggregate health report | | journal_list | read | All journal entries | | journal_latest | read | Most recent journal entry | | plan_merge | plan | Build (don't execute) a merge plan | | plan_promote_memory | plan | Build a single-memory promote plan | | plan_promote_cluster | plan | Build a whole-cluster promote plan | | apply_plan | write | Execute a Plan (journaled, undoable) | | undo | write | Reverse most recent (or specific) plan |

Plan tools never execute. Claude must explicitly call apply_plan — that's the confirmation surface.

Compared to existing tools

| Tool | Scope | What it does | What it doesn't | |---|---|---|---| | memex | Cross-project | Browse / lint / dedupe / promote / merge / journal-backed undo | (this is the gap) | | consolidate-memory (Anthropic, built-in) | One project | LLM-driven dedup inside a memory dir | Cross-project view, structural lint, undo | | dream-skill (community) | One project | Hook-triggered intra-project consolidation | Cross-project promotion | | mem0 / supermemory / vector-DB MCP servers | Separate store | Bolt a different memory store onto Claude | Don't touch the native ~/.claude/projects/*/memory/ format |

memex is the curator for the native auto-memory format, not a replacement store.

Status

Pre-1.0. The CLI commands and MCP server are stable and tested (191 unit + integration tests across 19 files, real end-to-end round-trips for every mutation: scan, lint, dedupe, merge, promote, undo, MCP, TUI). Tested on Node 20 and 22 on macOS and Ubuntu (see CI badge above). Windows untested.

Roadmap

• [x] v0.1: scan + parse, lint, doctor, dedupe (exact-match), merge, promote, undo, TUI, MCP
• [ ] v0.2: near-duplicate detection (TF-IDF char-3gram cosine, ~80 lines, zero new deps)
• [ ] v0.3: scheduled hook (auto-doctor weekly), conflict detection
• [ ] v0.4: semantic dedup (transformers.js + local MiniLM embedding)
• [ ] v1.0: when MCP TypeScript SDK v2 stabilizes

License

MIT — see LICENSE.