episodic-memory

Episodic Memory

Semantic search for Claude Code and Codex 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 a Codex plugin

This repository includes a Codex plugin manifest at .codex-plugin/plugin.json. Codex support requires codex-cli 0.130.0 or newer.

For local testing, build the plugin, add this repo as a local marketplace, then install/enable it from /plugins:

npm run build
codex features enable plugin_hooks
codex plugin marketplace add /path/to/episodic-memory

Then start Codex, open /plugins, install and enable episodic-memory from Episodic Memory Dev, open /hooks, review the Episodic Memory hook, and press t to trust it.

The Codex plugin:

• Syncs conversations from ~/.codex/sessions
• Exposes the same MCP search/read tools
• Installs the same memory skill, with Codex-specific direct MCP guidance
• Runs a SessionStart hook after the user reviews and trusts it in /hooks

Enable plugin hooks before relying on automatic sync:

codex features enable plugin_hooks

Then open /hooks in Codex, review the Episodic Memory hook, and press t to trust it. New or modified Codex hooks are listed but do not run until trusted.

See docs/CODEX.md for the full Codex setup, trust, troubleshooting, and E2E test workflow.

As an npm package

npm install -g github:obra/episodic-memory

Usage

Quick Start

# Sync conversations from Claude Code and Codex and index them
episodic-memory sync

# Search your conversation history
episodic-memory search "React Router authentication"

# View index statistics
episodic-memory stats

# Diagnose Codex setup
episodic-memory doctor codex

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