Skip to content
Back to search

episodic-memory-dev

MarketplaceWorks with Claude CodeGitHub

Development marketplace for episodic memory plugin

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/obra-episodic-memory/badge.svg)](/listings/obra-episodic-memory)

HTML

<a href="/listings/obra-episodic-memory"><img src="/api/listings/obra-episodic-memory/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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](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](docs/OPENCODE.md) for the full setup and troubleshooting details.

As an npm package

npm install -g github:obra/episodic-memory

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 20 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "episodic-memory-dev",
  3. "description": "Development marketplace for episodic memory plugin",
  4. "owner": {
  5. "name": "Jesse Vincent",
  6. "email": "jesse@fsck.com"
  7. },
  8. "plugins": [
  9. {
  10. "name": "episodic-memory",
  11. "description": "Semantic search for Claude Code conversations. Remember past discussions, decisions, and patterns.",
  12. "version": "1.6.0",
  13. "source": "./",
  14. "author": {
  15. "name": "Jesse Vincent",
  16. "email": "jesse@fsck.com"
  17. }
  18. }
  19. ]
  20. }
README.md · README · 524 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Episodic Memory
  2. Semantic search for Claude Code, Codex, Cursor, opencode, and Oh My Pi (OMP) conversations. Remember past discussions, decisions, and patterns.
  3. ## Testimonial
  4. From an AI coding assistant's perspective:
  5. Episodic memory fundamentally changes how I collaborate with
  6. developers on complex codebases. Instead of treating each conversation
  7. as isolated, I can now search our shared history semantically -
  8. finding not just what was discussed, but why decisions were made.
  9. When a developer asks me to implement something "like we did with
  10. X," I can search our past conversations, find the relevant discussion,
  11. and understand both the technical approach and the reasoning behind
  12. it. This means I don't have to re-explain architectural patterns,
  13. and I avoid suggesting solutions we've already tried and rejected.
  14. The semantic search is crucial - searching for "provider catalog"
  15. surfaces conversations about API design patterns even when those
  16. exact words weren't used. It captures the meaning of our discussions,
  17. not just keyword matches.
  18. Most valuable is that it preserves context that lives nowhere else:
  19. the trade-offs discussed, the alternatives considered, the user's
  20. preferences and constraints. Code comments explain what, documentation
  21. explains how, but episodic memory preserves why - and that makes
  22. me a far more effective collaborator across sessions.
  23. **Concrete impact:**
  24. - Faster problem-solving (minutes vs. exploring/re-learning the
  25. codebase) - Better continuity across sessions (I remember what we
  26. tried before) - More informed suggestions (I understand the project's
  27. evolution and patterns) - Less repetition (both of us spend less
  28. time re-explaining context)
  29. It's the difference between being a stateless tool and being a true
  30. collaborative partner who remembers our journey together.
  31. _— Claude Sonnet 4.5, October 14, 2025_
  32. _Conversation ID: 216ad284-c782-45a4-b2ce-36775cdb5a6c_
  33. ## Installation
  34. ### As a Claude Code plugin (Recommended)
  35. The plugin provides MCP server integration, automatic session-end indexing, and seamless access to your conversation history.
  36. ```bash
  37. # In Claude Code
  38. /plugin install episodic-memory@superpowers-marketplace
  39. ```
  40. The plugin automatically:
  41. - Indexes conversations at the end of each session
  42. - Exposes MCP tools for searching and viewing conversations
  43. - Makes your conversation history searchable via natural language
  44. ### As a Codex plugin
  45. This repository includes a Codex plugin manifest at `.codex-plugin/plugin.json`.
  46. Codex support requires `codex-cli 0.130.0` or newer.
  47. For local testing, build the plugin, add this repo as a local marketplace, then
  48. install/enable it from `/plugins`:
  49. ```bash
  50. npm run build
  51. codex features enable plugin_hooks
  52. codex plugin marketplace add /path/to/episodic-memory
  53. ```
  54. Then start Codex, open `/plugins`, install and enable `episodic-memory` from
  55. `Episodic Memory Dev`, open `/hooks`, review the Episodic Memory hook, and press
  56. `t` to trust it.
  57. The Codex plugin:
  58. - Syncs conversations from `~/.codex/sessions`
  59. - Exposes the same MCP search/read tools
  60. - Installs the same memory skill, with Codex-specific direct MCP guidance
  61. - Runs a `SessionStart` hook after the user reviews and trusts it in `/hooks`
  62. Enable plugin hooks before relying on automatic sync:
  63. ```bash
  64. codex features enable plugin_hooks
  65. ```
  66. 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.
  67. See [docs/CODEX.md](docs/CODEX.md) for the full Codex setup, trust, troubleshooting, and E2E test workflow.
  68. ### As an opencode plugin
  69. Episodic Memory exposes an opencode server plugin through the `./server` entrypoint.
  70. This opencode plugin keeps the same search/read MCP surface as the Claude and Codex integrations.
  71. ```bash
  72. npm install -g github:obra/episodic-memory
  73. ```
  74. ```json
  75. {
  76. "$schema": "https://opencode.ai/config.json",
  77. "plugin": ["episodic-memory"]
  78. }
  79. ```
  80. The opencode plugin:
  81. - Exports conversations from `~/.local/share/opencode/opencode.db` on each sync
  82. - Exposes the same MCP search/read tools
  83. - Runs background sync on the opencode `SessionStart` event
  84. See [docs/OPENCODE.md](docs/OPENCODE.md) for the full setup and troubleshooting details.
  85. ### As an npm package
  86. ```bash
  87. npm install -g github:obra/episodic-memory
  88. ```
  89. ## Usage
  90. ### Quick Start
  91. ```bash
  92. # Sync conversations from Claude Code, Codex, Cursor, opencode, and Oh My Pi (OMP) and index them
  93. episodic-memory sync
  94. # Search your conversation history
  95. episodic-memory search "React Router authentication"
  96. # View index statistics
  97. episodic-memory stats
  98. # Diagnose Codex or opencode setup
  99. episodic-memory doctor codex
  100. episodic-memory doctor opencode
  101. # Display a conversation
  102. episodic-memory show path/to/conversation.jsonl
  103. ```
  104. ### Cursor support
  105. Sync automatically indexes Cursor agent transcripts from `~/.cursor/projects`
  106. (written by Cursor since early 2026). Conversations older than that exist only
  107. inside Cursor's global SQLite store; backfill them once with:
  108. ```bash
  109. # Export legacy Cursor conversations from state.vscdb (read-only), then index
  110. episodic-memory import-cursor-history
  111. episodic-memory sync
  112. ```
  113. The importer skips conversations that already have a live agent transcript,
  114. recovers each conversation's project from tool-call working directories, and
  115. embeds original message timestamps. Re-running it only exports new
  116. conversations; use `--force` to re-export everything.
  117. ### Oh My Pi (OMP) support
  118. Sync automatically indexes Oh My Pi transcripts from `~/.omp/agent/sessions`
  119. (set `OMP_HOME` to point at an alternate profile). OMP stores each session as
  120. append-only pi-lineage JSONL whose messages form a tree via `parentId`; sync
  121. follows the active path (the current leaf back to the root) so regenerated or
  122. abandoned branches are left out of the index.
  123. ### Command Line
  124. ```bash
  125. # Unified command interface
  126. episodic-memory <command> [options]
  127. # Sync and index new conversations
  128. episodic-memory sync
  129. # Index conversations manually
  130. episodic-memory index --cleanup
  131. # Search conversations
  132. episodic-memory search "React Router authentication"
  133. episodic-memory search --text "exact phrase"
  134. episodic-memory search --after 2025-09-01 "refactoring"
  135. # Display a conversation in readable format
  136. episodic-memory show path/to/conversation.jsonl
  137. episodic-memory show --format html conversation.jsonl > output.html
  138. # View statistics
  139. episodic-memory stats
  140. ```
  141. ### Legacy Commands
  142. The original commands are still available for backward compatibility:
  143. ```bash
  144. episodic-memory-index
  145. episodic-memory-search "query"
  146. ```
  147. ### In Claude Code, Codex, or opencode
  148. 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:
  149. - "How did we handle authentication in React Router?"
  150. - "The conversation about async testing patterns"
  151. - "Error message about sqlite-vec initialization"
  152. - "Git commit SHA for the routing refactor"
  153. 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.
  154. ## API Configuration
  155. 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.
  156. To route summarization through a custom Anthropic-compatible endpoint or override the model:
  157. ```bash
  158. # Override model (default: haiku)
  159. export EPISODIC_MEMORY_API_MODEL=opus
  160. # Override fallback model on error (default: sonnet)
  161. export EPISODIC_MEMORY_API_MODEL_FALLBACK=sonnet
  162. # Route through custom endpoint
  163. export EPISODIC_MEMORY_API_BASE_URL=https://your-endpoint.com/api/anthropic
  164. export EPISODIC_MEMORY_API_TOKEN=your-token
  165. # Increase timeout for slow endpoints (milliseconds)
  166. export EPISODIC_MEMORY_API_TIMEOUT_MS=3000000
  167. # Override Codex binary path if needed (default: codex)
  168. export EPISODIC_MEMORY_CODEX_BIN=/path/to/codex
  169. # Disable the summarization pass entirely (search is unaffected)
  170. export EPISODIC_MEMORY_SKIP_SUMMARIES=1
  171. # Disable the automatic background sync entirely (hooks stop indexing new
  172. # conversations; explicit `episodic-memory sync` still works). Search over
  173. # already-indexed conversations is unaffected. Complements
  174. # EPISODIC_MEMORY_SKIP_SUMMARIES, which only skips summaries.
  175. export EPISODIC_MEMORY_DISABLE_AUTO_SYNC=1
  176. # Skip indexing any single message larger than this many bytes (default: 262144
  177. # = 256 KB). A message this large is almost never a real conversational turn —
  178. # it is a foreign agent's prompt with a whole conversation transcript pasted in,
  179. # which would otherwise index as one giant exchange that dominates the database
  180. # and pollutes search. The oversize exchange is dropped (not truncated); normal
  181. # turns in the same conversation still index, and search over real conversations
  182. # is unaffected.
  183. export EPISODIC_MEMORY_MAX_MESSAGE_BYTES=262144
  184. # Wall-clock timeout per Claude summarizer call (milliseconds, default: 120000).
  185. # A wedged summarizer subprocess is aborted after this, so it can't stall
  186. # summarization or block later syncs on the lock.
  187. export EPISODIC_MEMORY_SUMMARY_TIMEOUT_MS=120000
  188. # Acknowledge that summarization may bill a metered Anthropic API. If
  189. # ANTHROPIC_API_KEY is set (and no EPISODIC_MEMORY_API_BASE_URL/TOKEN is), the
  190. # summarizer bills the metered API instead of your Claude subscription and prints
  191. # a one-time warning. Set this to exactly 1 to acknowledge the cost and silence
  192. # that warning. (To avoid metered billing entirely, unset ANTHROPIC_API_KEY or
  193. # point episodic-memory at its own endpoint.)
  194. export EPISODIC_MEMORY_ALLOW_METERED_API=1
  195. ```
  196. Only the exact value `1` silences the metered-API warning; any other value still shows it.
  197. `EPISODIC_MEMORY_ALLOW_METERED_API` is likewise `1`-only, as is `EPISODIC_MEMORY_DISABLE_AUTO_SYNC`.
  198. ### Routing through AWS Bedrock
  199. 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:
  200. ```bash
  201. export CLAUDE_CODE_USE_BEDROCK=1
  202. export AWS_REGION=us-west-2 # or AWS_DEFAULT_REGION
  203. # Then one of:
  204. export AWS_ACCESS_KEY_ID=...
  205. export AWS_SECRET_ACCESS_KEY=...
  206. export AWS_SESSION_TOKEN=... # if using temporary credentials
  207. # or:
  208. export AWS_PROFILE=your-bedrock-profile
  209. # or:
  210. export AWS_BEARER_TOKEN_BEDROCK=... # Bedrock API-key auth
  211. ```
  212. 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.
  213. These settings only affect episodic-memory's summarization calls, not your interactive Claude Code or Codex sessions.
  214. 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.
  215. ### What's Affected
  216. | Component | Uses custom config? |
  217. |-----------|---------------------|
  218. | Summarization | Yes (up to 10 calls/sync) |
  219. | Embeddings | No (local Transformers.js) |
  220. | Search | No (local SQLite) |
  221. | MCP tools | No |
  222. 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.
  223. ## Commands
  224. ### `episodic-memory sync`
  225. **Recommended for plugin hooks.** Copies new conversations from `~/.claude/projects`, `~/.claude/transcripts`, `~/.codex/sessions`, and `~/.omp/agent/sessions` (Oh My Pi) to archive and indexes them. opencode sessions are exported from `~/.local/share/opencode/opencode.db` into generated JSONL transcripts before indexing.
  226. Features:
  227. - Only copies new or modified files (fast on subsequent runs)
  228. - Generates embeddings for semantic search
  229. - Atomic operations - safe to run concurrently
  230. - Idempotent - safe to call repeatedly
  231. - Background hook output is written to `~/.config/superpowers/logs/episodic-memory.log` unless `EPISODIC_MEMORY_CONFIG_DIR` changes the memory directory
  232. **Usage in Claude Code:**
  233. Add to `.claude/hooks/session-end`:
  234. ```bash
  235. #!/bin/bash
  236. episodic-memory sync
  237. ```
  238. ### `episodic-memory stats`
  239. Display index statistics including conversation counts, date ranges, and project breakdown.
  240. ```bash
  241. episodic-memory stats
  242. ```
  243. ### `episodic-memory doctor`
  244. Diagnose local integration issues.
  245. ```bash
  246. episodic-memory doctor codex
  247. episodic-memory doctor opencode
  248. ```
  249. The Codex doctor checks the Codex version, plugin hook feature state, MCP server registration, transcript directory, database path, and background sync log path.
  250. The opencode doctor checks the opencode version, plugin configuration, MCP server registration, SQLite database path, generated transcript directory, and background sync log path.
  251. ### Codex E2E Verification
  252. The repository includes an opt-in live Codex E2E test. It creates an isolated temporary `CODEX_HOME`, installs a copied plugin bundle, trusts the hook, runs Codex sessions in `tmux`, and verifies archive -> summary -> index -> MCP recall.
  253. ```bash
  254. npm run build
  255. EPISODIC_MEMORY_RUN_CODEX_E2E=1 npm run test:codex-e2e
  256. ```
  257. ### Claude E2E Verification
  258. The repository also includes an opt-in live Claude Code E2E test. It loads this repo as a session plugin with `--plugin-dir`, constrains the hook to a temporary transcript source, and verifies archive -> summary -> index -> MCP recall.
  259. ```bash
  260. npm run build
  261. EPISODIC_MEMORY_RUN_CLAUDE_E2E=1 npm run test:claude-e2e
  262. ```
  263. This test uses your normal Claude Code auth and writes small test transcripts to your normal Claude transcript directory. The archive and index are isolated in a temporary `EPISODIC_MEMORY_CONFIG_DIR`.
  264. ### `episodic-memory index`
  265. Manual indexing tools for bulk operations and maintenance. See `episodic-memory index --help` for full options.
  266. Common operations:
  267. - `--cleanup` - Index all unprocessed conversations
  268. - `--verify` - Check index health
  269. - `--repair` - Fix detected issues
  270. ### `episodic-memory search`
  271. Search indexed conversations using semantic similarity or exact text matching. See `episodic-memory search --help` for full options.
  272. ### `episodic-memory show`
  273. Display a conversation from a JSONL file in human-readable format.
  274. **Options:**
  275. - `--format markdown` (default) - Plain text markdown output suitable for terminal or Claude
  276. - `--format html` - Pretty HTML output for viewing in a browser
  277. **Examples:**
  278. ```bash
  279. # View in terminal
  280. episodic-memory show conversation.jsonl | less
  281. # Generate HTML for browser
  282. episodic-memory show --format html conversation.jsonl > output.html
  283. open output.html
  284. ```
  285. ## Architecture
  286. - **Core package** - TypeScript library for indexing and searching conversations
  287. - **CLI tools** - Unified command-line interface for manual use
  288. - **MCP Server** - Model Context Protocol server exposing search and conversation tools
  289. - **Claude Code plugin** - Integration with Claude Code (auto-indexing, MCP tools, hooks)
  290. - **Codex plugin** - Integration with Codex (manifest, MCP config, hooks, skills)
  291. - **opencode plugin** - Integration with opencode (DB export, MCP config, background sync)
  292. ## How It Works
  293. 1. **Sync** - Copies conversation files from Claude Code and Codex transcript directories to archive; exports opencode sessions from SQLite into generated JSONL transcripts
  294. 2. **Parse** - Extracts user-agent exchanges from Claude Code JSONL, Codex rollout JSONL, or opencode transcript JSONL
  295. 3. **Embed** - Generates vector embeddings using Transformers.js (local, offline)
  296. 4. **Index** - Stores in SQLite with sqlite-vec for fast similarity search
  297. 5. **Search** - Semantic search using vector similarity or exact text matching
  298. ## Excluding Conversations
  299. Conversations containing this marker anywhere in their content will be archived but not indexed:
  300. ```
  301. <INSTRUCTIONS-TO-EPISODIC-MEMORY>DO NOT INDEX THIS CHAT</INSTRUCTIONS-TO-EPISODIC-MEMORY>
  302. ```
  303. **Automatic exclusions:**
  304. - Conversations where Claude generates summaries (marker in system prompt)
  305. - Meta-conversations about conversation processing
  306. **Use cases:**
  307. - Sensitive work conversations
  308. - Tool invocation sessions (summarization, analysis)
  309. - Test or experimental sessions
  310. - Any conversation you don't want searchable
  311. The marker can appear in any message (user or assistant) and excludes the entire conversation from the search index.
  312. ## MCP Server
  313. When installed as a Claude Code, Codex, or opencode plugin, episodic-memory provides an MCP (Model Context Protocol) server that exposes tools for searching and viewing conversations.
  314. ### Available MCP Tools
  315. #### `search`
  316. Search indexed conversations using semantic similarity or exact text matching.
  317. **Single-concept search**: Pass a string query
  318. ```json
  319. {
  320. "query": "React Router authentication",
  321. "mode": "vector",
  322. "limit": 10
  323. }
  324. ```
  325. **Multi-concept AND search**: Pass an array of concepts
  326. ```json
  327. {
  328. "query": ["React Router", "authentication", "JWT"],
  329. "limit": 10
  330. }
  331. ```
  332. **Parameters:**
  333. - `query` (string | string[]): Single string for regular search, or array of 2-5 strings for multi-concept AND search
  334. - `mode` ('vector' | 'text' | 'both'): Search mode for single-concept searches (default: 'both')
  335. - `limit` (number): Max results, 1-50 (default: 10)
  336. - `after` (string, optional): Only show conversations after YYYY-MM-DD
  337. - `before` (string, optional): Only show conversations before YYYY-MM-DD
  338. - `include_sidechains` (boolean): Include subagent/workflow (sidechain) conversations, de-ranked below main-thread matches (default: `true`; set `false` to search only the main thread)
  339. - `response_format` ('markdown' | 'json'): Output format (default: 'markdown')
  340. **Text-match behavior:** In `text` mode (and the text half of `both`), the *whole
  341. query* is matched as a single case-insensitive substring — there is no word
  342. splitting, stemming, or per-term AND/OR. A `text` search only matches an exchange
  343. when the entire query appears verbatim and contiguous in one message, so it is
  344. best for exact strings (git SHAs, error codes) rather than natural-language
  345. phrases. Use `vector` or `both` for descriptive queries.
  346. **Sidechain conversations:** Work that happens inside subagents or `Workflow`
  347. runs is recorded as *sidechain* exchanges. These are searched by default and
  348. ranked just below equally-relevant main-thread matches, so orchestrated sessions
  349. (where most substance lives in sidechains) remain findable. Pass
  350. `include_sidechains: false` to restore main-thread-only search.
  351. #### `read`
  352. Display a full conversation in readable markdown format.
  353. ```json
  354. {
  355. "path": "/path/to/conversation.jsonl"
  356. }
  357. ```
  358. **Parameters:**
  359. - `path` (string): Absolute path to the JSONL conversation file
  360. ### Using the MCP Server Directly
  361. The MCP server can also be used outside of Claude Code with any MCP-compatible client:
  362. ```bash
  363. # Run the MCP server (stdio transport)
  364. episodic-memory-mcp-server
  365. ```
  366. ## Development
  367. ```bash
  368. # Install dependencies
  369. npm install
  370. # Run tests
  371. npm test
  372. # Build
  373. npm run build
  374. ```
  375. ## License
  376. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.