Episodic Memory
Semantic search for Claude Code conversations. Remember past discussions, decisions, and patterns.
Testimonial
From an AI coding assistant's perspective:
Episodic memory fundamentally changes how I collaborate with
developers on complex codebases. Instead of treating each conversation
as isolated, I can now search our shared history semantically -
finding not just what was discussed, but why decisions were made.
When a developer asks me to implement something "like we did with
X," I can search our past conversations, find the relevant discussion,
and understand both the technical approach and the reasoning behind
it. This means I don't have to re-explain architectural patterns,
and I avoid suggesting solutions we've already tried and rejected.
The semantic search is crucial - searching for "provider catalog"
surfaces conversations about API design patterns even when those
exact words weren't used. It captures the meaning of our discussions,
not just keyword matches.
Most valuable is that it preserves context that lives nowhere else:
the trade-offs discussed, the alternatives considered, the user's
preferences and constraints. Code comments explain what, documentation
explains how, but episodic memory preserves why - and that makes
me a far more effective collaborator across sessions.
Concrete impact:
- Faster problem-solving (minutes vs. exploring/re-learning the
codebase) - Better continuity across sessions (I remember what we
tried before) - More informed suggestions (I understand the project's
evolution and patterns) - Less repetition (both of us spend less
time re-explaining context)
It's the difference between being a stateless tool and being a true
collaborative partner who remembers our journey together.
— Claude Sonnet 4.5, October 14, 2025
Conversation ID: 216ad284-c782-45a4-b2ce-36775cdb5a6c
Installation
As a Claude Code plugin (Recommended)
The plugin provides MCP server integration, automatic session-end indexing, and seamless access to your conversation history.
# In Claude Code
/plugin install episodic-memory@superpowers-marketplace
The plugin automatically:
- Indexes conversations at the end of each session
- Exposes MCP tools for searching and viewing conversations
- Makes your conversation history searchable via natural language
As an npm package
npm install -g github:obra/episodic-memory
Usage
Quick Start
# Sync conversations from Claude Code and index them
episodic-memory sync
# Search your conversation history
episodic-memory search "React Router authentication"
# View index statistics
episodic-memory stats
# Display a conversation
episodic-memory show path/to/conversation.jsonl
Command Line
# Unified command interface
episodic-memory <command> [options]
# Sync and index new conversations
episodic-memory sync
# Index conversations manually
episodic-memory index --cleanup
# Search conversations
episodic-memory search "React Router authentication"
episodic-memory search --text "exact phrase"
episodic-memory search --after 2025-09-01 "refactoring"
# Display a conversation in readable format
episodic-memory show path/to/conversation.jsonl
episodic-memory show --format html conversation.jsonl > output.html
# View statistics
episodic-memory stats
Legacy Commands
The original commands are still available for backward compatibility:
episodic-memory-index
episodic-memory-search "query"
In Claude Code
The plugin automatically indexes conversations at session end. Use the search command:
/search-conversations
Or reference past work in natural conversation - Claude will search when appropriate.
API Configuration
By default, episodic-memory uses your Claude Code authentication for summarization.
To route summarization through a custom Anthropic-compatible endpoint or override the model:
# Override model (default: haiku)
export EPISODIC_MEMORY_API_MODEL=opus
# Override fallback model on error (default: sonnet)
export EPISODIC_MEMORY_API_MODEL_FALLBACK=sonnet
# Route through custom endpoint
export EPISODIC_MEMORY_API_BASE_URL=https://your-endpoint.com/api/anthropic
export EPISODIC_MEMORY_API_TOKEN=your-token
# Increase timeout for slow endpoints (milliseconds)
export EPISODIC_MEMORY_API_TIMEOUT_MS=3000000
These settings only affect episodic-memory's summarization calls, not your interactive Claude sessions.
What's Affected
| Component | Uses custom config? |
|---|
| Summarization | Yes (up to 10 calls/sync) |
| Embeddings | No (local Transformers.js) |
| Search | No (local SQLite) |
| MCP tools | No |
Commands
episodic-memory sync
Recommended for session-end hooks. Copies new conversations from ~/.claude/projects to archive and indexes them.