episodic-memory

Episodic Memory

Semantic search for Claude Code, Codex, Cursor, opencode, and Oh My Pi (OMP) 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 opencode plugin

Episodic Memory exposes an opencode server plugin through the ./server entrypoint. This opencode plugin keeps the same search/read MCP surface as the Claude and Codex integrations.

npm install -g github:obra/episodic-memory

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["episodic-memory"]
}

The opencode plugin:

• Exports conversations from ~/.local/share/opencode/opencode.db on each sync
• Exposes the same MCP search/read tools
• Runs background sync on the opencode SessionStart event

See docs/OPENCODE.md for the full setup and troubleshooting details.

As an npm package

npm install -g github:obra/episodic-memory

Usage

Quick Start

# Sync conversations from Claude Code, Codex, Cursor, opencode, and Oh My Pi (OMP) and index them
episodic-memory sync

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

# View index statistics
episodic-memory stats

# Diagnose Codex or opencode setup
episodic-memory doctor codex
episodic-memory doctor opencode

# Display a conversation
episodic-memory show path/to/conversation.jsonl

Cursor support

Sync automatically indexes Cursor agent transcripts from ~/.cursor/projects (written by Cursor since early 2026). Conversations older than that exist only inside Cursor's global SQLite store; backfill them once with:

# Export legacy Cursor conversations from state.vscdb (read-only), then index
episodic-memory import-cursor-history
episodic-memory sync

The importer skips conversations that already have a live agent transcript, recovers each conversation's project from tool-call working directories, and embeds original message timestamps. Re-running it only exports new conversations; use --force to re-export everything.

Oh My Pi (OMP) support

Sync automatically indexes Oh My Pi transcripts from ~/.omp/agent/sessions (set OMP_HOME to point at an alternate profile). OMP stores each session as append-only pi-lineage JSONL whose messages form a tree via parentId; sync follows the active path (the current leaf back to the root) so regenerated or abandoned branches are left out of the index.

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, Codex, or opencode

The plugin automatically syncs and indexes conversations from the harness that starts it. Reference past work in natural conversation — the remembering-conversations skill dispatches the search-conversations agent automatically when recall is needed. Example prompts:

• "How did we handle authentication in React Router?"
• "The conversation about async testing patterns"
• "Error message about sqlite-vec initialization"
• "Git commit SHA for the routing refactor"

In Codex and opencode, the skill guides the agent to use the episodic-memory MCP search/read tools directly when an agent-dispatch path is not available.

API Configuration

By default, episodic-memory uses your Claude Code authentication for Claude Code summarization. Codex-indexed sessions with a session ID are summarized through codex app-server by creating an ephemeral thread/fork, so the summary can use Codex session context and reasoning summaries without appending to the original rollout.

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

# Override Codex binary path if needed (default: codex)
export EPISODIC_MEMORY_CODEX_BIN=/path/to/codex

# Disable the summarization pass entirely (search is unaffected)
export EPISODIC_MEMORY_SKIP_SUMMARIES=1

# Disable the automatic background sync entirely (hooks stop indexing new
# conversations; explicit `episodic-memory sync` still works). Search over
# already-indexed conversations is unaffected. Complements
# EPISODIC_MEMORY_SKIP_SUMMARIES, which only skips summaries.
export EPISODIC_MEMORY_DISABLE_AUTO_SYNC=1

# Skip indexing any single message larger than this many bytes (default: 262144
# = 256 KB). A message this large is almost never a real conversational turn —
# it is a foreign agent's prompt with a whole conversation transcript pasted in,
# which would otherwise index as one giant exchange that dominates the database
# and pollutes search. The oversize exchange is dropped (not truncated); normal
# turns in the same conversation still index, and search over real conversations
# is unaffected.
export EPISODIC_MEMORY_MAX_MESSAGE_BYTES=262144

# Wall-clock timeout per Claude summarizer call (milliseconds, default: 120000).
# A wedged summarizer subprocess is aborted after this, so it can't stall
# summarization or block later syncs on the lock.
export EPISODIC_MEMORY_SUMMARY_TIMEOUT_MS=120000

# Acknowledge that summarization may bill a metered Anthropic API. If
# ANTHROPIC_API_KEY is set (and no EPISODIC_MEMORY_API_BASE_URL/TOKEN is), the
# summarizer bills the metered API instead of your Claude subscription and prints
# a one-time warning. Set this to exactly 1 to acknowledge the cost and silence
# that warning. (To avoid metered billing entirely, unset ANTHROPIC_API_KEY or
# point episodic-memory at its own endpoint.)
export EPISODIC_MEMORY_ALLOW_METERED_API=1

Only the exact value 1 silences the metered-API warning; any other value still shows it. EPISODIC_MEMORY_ALLOW_METERED_API is likewise 1-only, as is EPISODIC_MEMORY_DISABLE_AUTO_SYNC.

Routing through AWS Bedrock

To route Claude summarization through AWS Bedrock instead of the Anthropic API, set CLAUDE_CODE_USE_BEDROCK and provide AWS credentials in the plugin's environment:

export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-west-2          # or AWS_DEFAULT_REGION

# Then one of:
export AWS_ACCESS_KEY_ID=...
export AWS_SECRET_ACCESS_KEY=...
export AWS_SESSION_TOKEN=...         # if using temporary credentials

# or:
export AWS_PROFILE=your-bedrock-profile

# or:
export AWS_BEARER_TOKEN_BEDROCK=...  # Bedrock API-key auth

These pass through unchanged to episodic-memory's summarizer subprocess. Because Bedrock authenticates with AWS credentials rather than ANTHROPIC_API_KEY, it does not trigger the metered-API warning above.

These settings only affect episodic-memory's summarization calls, not your interactive Claude Code or Codex sessions.

Codex summarization requires codex-cli 0.130.0 or newer. If Codex app-server summarization is unavailable, sync logs the reason and falls back to transcript-text summarization.

What's Affected

Summaries are display-only: they decorate search results and are never embedded or searched, so EPISODIC_MEMORY_SKIP_SUMMARIES=1 costs you that line of context and nothing else.

Commands

episodic-memory sync