memem

# memem

> memem is a Claude Code plugin that gives Claude persistent memory across every session. It auto-extracts decisions, conventions, and lessons from completed sessions via a background miner, stores them as markdown files in an Obsidian vault, and assembles query-tailored context briefings at the start of each new session — so you stop re-explaining your project every time.

Quality: validated by the [Glama MCP registry](https://glama.ai/mcp/servers/TT-Wang/cortex-plugin) — ![score](https://glama.ai/mcp/servers/TT-Wang/cortex-plugin/badges/score.svg?v=4)

memem is **local-first**: no cloud services, no vendor lock-in, no API keys required. Memories live as human-readable markdown in `~/obsidian-brain/memem/memories/`. A SQLite FTS5 index provides fast machine search. Claude Haiku (via the `claude` CLI) handles query-tailored assembly and mining, but gracefully degrades to FTS-only keyword recall when the CLI isn't available.

Install is one command (`/plugin install memem`) and the plugin self-heals its Python dependencies via a `uv`-backed bootstrap shim on first run — no separate `pip install` step.

## When to use memem

- You use Claude Code daily and keep re-explaining your project to every new session
- You want durable, searchable, human-readable memory your AI can use across all projects
- You already use Obsidian or like the idea of a browsable markdown knowledge graph
- You want local-first AI memory with zero vendor lock-in

## When NOT to use memem

- You already have CLAUDE.md working well and don't want background processes
- You want cloud-synced memory across machines (memem is local-only)
- You don't have Python 3.11+ available

## Docs

- [README](https://github.com/TT-Wang/memem/blob/master/README.md): install, usage, MCP tool reference
- [CHANGELOG](https://github.com/TT-Wang/memem/blob/master/CHANGELOG.md): version history
- [CONTRIBUTING](https://github.com/TT-Wang/memem/blob/master/CONTRIBUTING.md): dev setup

## Install

```bash
/plugin marketplace add TT-Wang/memem
/plugin install memem
```

First-session MCP spawn runs `bootstrap.sh` which installs `uv`, syncs deps into a plugin-local `.venv`, verifies directory writability, probes for the `claude` CLI, and writes `~/.memem/.capabilities`. Total first-run overhead: ~5 seconds. Warm start: ~100ms.

## How it differs from vanilla CLAUDE.md

- Automatic extraction instead of manual editing
- Query-tailored context at session start instead of a static dump
- Self-evolving corpus (merges redundant memories, deprecates outdated ones)
- Cross-project (one shared knowledge graph, not per-repo)
- Security scanning on every write (prompt injection, credential exfil)
- Browsable Obsidian vault with graph view and backlinks

## Key concepts

- **Event-triggered miner**: Stop hook spawns a detached `mine_delta` subprocess after each conversation turn; extracts durable lessons via Haiku and writes them as markdown (no daemon since v2.1.0)
- **Profiles (v2.8.0)**: schema-shaped always-injected documents at `<vault>/memem/profiles/`. `profile_user.md` (Preferences / Conventions / Environment) and `profile_<project>.md` (Identity / Stack & Structure / Conventions). Populated by the miner's `PROFILE` reconcile op; bootstrapped from legacy vault via `--migrate-layers`.
- **Working rules (v2.8.0)**: `type:procedural` memories (failure→fix, corrections) ranked by citation count, injected as `## Working rules` at session start (≤1200 chars).
- **Context assembly**: session start injects profiles + working rules + episode index; everything else is on-demand via recall tools
- **Reconcile-at-write pipeline**: ADD / UPDATE / SUPERSEDE / NOOP / PROFILE — how new mined memories evolve the existing corpus. Each candidate compared against its top-5 vault neighbors in one batched Haiku call; SUPERSEDE bi-temporally invalidates the replaced memory.
- **Dream cycles (v2.8.0)**: background dreamer categories — `cluster_merge` (consolidation), `reflection_with_citations` (insight synthesis), `tense_rewrite` (expired future-tense correction). `--dream --safe-auto` applies additive categories automatically; fires every 25 substantive mining deltas.
- **Degraded mode**: when `claude` CLI is missing, memem falls back to FTS-only keyword recall instead of failing

## MCP tools exposed to the LLM

- `memory_save(content, title, tags)`: store a lesson (security-scanned; `layer` param deprecated in v2.8.0)
- `memory_recall(query, limit)`: search memories (unified engine: three-way RRF — semantic + BM25 + FTS5 — with usage/scope/link/importance signals and MMR)
- `memory_list()`: list all memories with stats
- `memory_import(source_path)`: import from files, directories, chat exports
- `transcript_search(query)`: search raw Claude Code session logs
- `context_assemble(query, project)`: on-demand query-tailored briefing from all knowledge

## Slash commands

- `/memem`: welcome + status + help
- `/memem-status`: memory count, projects, miner health
- `/memem-doctor`: preflight health check with fix instructions
- `/memem-mine`: opt in to event-triggered mining (Stop hook mines on every session)
- `/memem-mine-history`: opt-in to mine pre-install sessions

## Requirements

- Claude Code
- Python 3.11+
- `uv` (auto-installed by bootstrap.sh if missing)
- `claude` CLI on PATH (optional — required for Haiku-powered assembly; FTS-only degraded mode works without it)

## Companion project

- **forge** — https://github.com/TT-Wang/forge — structured planning,
  parallel execution, and deep validation for Claude Code. Recommended
  pairing: forge plans + executes multi-file changes, memem remembers
  what worked. Forge's `memory_save` patterns land in memem's recall
  index, so learnings compound across runs.

## License

MIT