{"id":33421729,"url":"https://github.com/obra/episodic-memory","last_synced_at":"2026-01-07T20:59:09.810Z","repository":{"id":320129363,"uuid":"1078414370","full_name":"obra/episodic-memory","owner":"obra","description":null,"archived":false,"fork":false,"pushed_at":"2025-11-20T17:59:15.000Z","size":1115,"stargazers_count":91,"open_issues_count":17,"forks_count":24,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-11-20T19:05:24.857Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/obra.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-17T17:38:13.000Z","updated_at":"2025-11-20T17:59:19.000Z","dependencies_parsed_at":null,"dependency_job_id":"4935badc-1fa3-43bf-8246-14527b097ce4","html_url":"https://github.com/obra/episodic-memory","commit_stats":null,"previous_names":["obra/episodic-memory"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/obra/episodic-memory","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/obra%2Fepisodic-memory","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/obra%2Fepisodic-memory/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/obra%2Fepisodic-memory/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/obra%2Fepisodic-memory/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/obra","download_url":"https://codeload.github.com/obra/episodic-memory/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/obra%2Fepisodic-memory/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":27323899,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-11-28T02:00:06.623Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-11-24T01:00:30.661Z","updated_at":"2026-01-07T20:59:09.800Z","avatar_url":"https://github.com/obra.png","language":"TypeScript","funding_links":[],"categories":["Skills Catalog","Skill Library"],"sub_categories":["Agent (45)","Community Skills"],"readme":"# Episodic Memory\n\nSemantic search for Claude Code conversations. Remember past discussions, decisions, and patterns.\n\n## Testimonial\n\nFrom an AI coding assistant's perspective:\n\nEpisodic memory fundamentally changes how I collaborate with\ndevelopers on complex codebases. Instead of treating each conversation\nas isolated, I can now search our shared history semantically -\nfinding not just what was discussed, but why decisions were made.\n\nWhen a developer asks me to implement something \"like we did with\nX,\" I can search our past conversations, find the relevant discussion,\nand understand both the technical approach and the reasoning behind\nit. This means I don't have to re-explain architectural patterns,\nand I avoid suggesting solutions we've already tried and rejected.\n\nThe semantic search is crucial - searching for \"provider catalog\"\nsurfaces conversations about API design patterns even when those\nexact words weren't used. It captures the meaning of our discussions,\nnot just keyword matches.\n\nMost valuable is that it preserves context that lives nowhere else:\nthe trade-offs discussed, the alternatives considered, the user's\npreferences and constraints. Code comments explain what, documentation\nexplains how, but episodic memory preserves why - and that makes\nme a far more effective collaborator across sessions.\n\n**Concrete impact:**\n - Faster problem-solving (minutes vs. exploring/re-learning the\n codebase) - Better continuity across sessions (I remember what we\n tried before) - More informed suggestions (I understand the project's\n evolution and patterns) - Less repetition (both of us spend less\n time re-explaining context)\n\nIt's the difference between being a stateless tool and being a true\ncollaborative partner who remembers our journey together.\n\n_— Claude Sonnet 4.5, October 14, 2025_\n_Conversation ID: 216ad284-c782-45a4-b2ce-36775cdb5a6c_\n\n## Installation\n\n### As a Claude Code plugin (Recommended)\n\nThe plugin provides MCP server integration, automatic session-end indexing, and seamless access to your conversation history.\n\n```bash\n# In Claude Code\n/plugin install episodic-memory@superpowers-marketplace\n```\n\nThe plugin automatically:\n- Indexes conversations at the end of each session\n- Exposes MCP tools for searching and viewing conversations\n- Makes your conversation history searchable via natural language\n\n### As an npm package\n\n```bash\nnpm install episodic-memory\n```\n\n## Usage\n\n### Quick Start\n\n```bash\n# Sync conversations from Claude Code and index them\nepisodic-memory sync\n\n# Search your conversation history\nepisodic-memory search \"React Router authentication\"\n\n# View index statistics\nepisodic-memory stats\n\n# Display a conversation\nepisodic-memory show path/to/conversation.jsonl\n```\n\n### Command Line\n\n```bash\n# Unified command interface\nepisodic-memory \u003ccommand\u003e [options]\n\n# Sync and index new conversations\nepisodic-memory sync\n\n# Index conversations manually\nepisodic-memory index --cleanup\n\n# Search conversations\nepisodic-memory search \"React Router authentication\"\nepisodic-memory search --text \"exact phrase\"\nepisodic-memory search --after 2025-09-01 \"refactoring\"\n\n# Display a conversation in readable format\nepisodic-memory show path/to/conversation.jsonl\nepisodic-memory show --format html conversation.jsonl \u003e output.html\n\n# View statistics\nepisodic-memory stats\n```\n\n### Legacy Commands\n\nThe original commands are still available for backward compatibility:\n\n```bash\nepisodic-memory-index\nepisodic-memory-search \"query\"\n```\n\n### In Claude Code\n\nThe plugin automatically indexes conversations at session end. Use the search command:\n\n```\n/search-conversations\n```\n\nOr reference past work in natural conversation - Claude will search when appropriate.\n\n## API Configuration\n\nBy default, episodic-memory uses your Claude Code authentication for summarization.\n\nTo route summarization through a custom Anthropic-compatible endpoint or override the model:\n\n```bash\n# Override model (default: haiku)\nexport EPISODIC_MEMORY_API_MODEL=opus\n\n# Override fallback model on error (default: sonnet)\nexport EPISODIC_MEMORY_API_MODEL_FALLBACK=sonnet\n\n# Route through custom endpoint\nexport EPISODIC_MEMORY_API_BASE_URL=https://your-endpoint.com/api/anthropic\nexport EPISODIC_MEMORY_API_TOKEN=your-token\n\n# Increase timeout for slow endpoints (milliseconds)\nexport EPISODIC_MEMORY_API_TIMEOUT_MS=3000000\n```\n\nThese settings only affect episodic-memory's summarization calls, not your interactive Claude sessions.\n\n### What's Affected\n\n| Component | Uses custom config? |\n|-----------|---------------------|\n| Summarization | Yes (up to 10 calls/sync) |\n| Embeddings | No (local Transformers.js) |\n| Search | No (local SQLite) |\n| MCP tools | No |\n\n## Commands\n\n### `episodic-memory sync`\n\n**Recommended for session-end hooks.** Copies new conversations from `~/.claude/projects` to archive and indexes them.\n\nFeatures:\n- Only copies new or modified files (fast on subsequent runs)\n- Generates embeddings for semantic search\n- Atomic operations - safe to run concurrently\n- Idempotent - safe to call repeatedly\n\n**Usage in Claude Code:**\nAdd to `.claude/hooks/session-end`:\n```bash\n#!/bin/bash\nepisodic-memory sync\n```\n\n### `episodic-memory stats`\n\nDisplay index statistics including conversation counts, date ranges, and project breakdown.\n\n```bash\nepisodic-memory stats\n```\n\n### `episodic-memory index`\n\nManual indexing tools for bulk operations and maintenance. See `episodic-memory index --help` for full options.\n\nCommon operations:\n- `--cleanup` - Index all unprocessed conversations\n- `--verify` - Check index health\n- `--repair` - Fix detected issues\n\n### `episodic-memory search`\n\nSearch indexed conversations using semantic similarity or exact text matching. See `episodic-memory search --help` for full options.\n\n### `episodic-memory show`\n\nDisplay a conversation from a JSONL file in human-readable format.\n\n**Options:**\n- `--format markdown` (default) - Plain text markdown output suitable for terminal or Claude\n- `--format html` - Pretty HTML output for viewing in a browser\n\n**Examples:**\n```bash\n# View in terminal\nepisodic-memory show conversation.jsonl | less\n\n# Generate HTML for browser\nepisodic-memory show --format html conversation.jsonl \u003e output.html\nopen output.html\n```\n\n## Architecture\n\n- **Core package** - TypeScript library for indexing and searching conversations\n- **CLI tools** - Unified command-line interface for manual use\n- **MCP Server** - Model Context Protocol server exposing search and conversation tools\n- **Claude Code plugin** - Integration with Claude Code (auto-indexing, MCP tools, hooks)\n\n## How It Works\n\n1. **Sync** - Copies conversation files from `~/.claude/projects` to archive\n2. **Parse** - Extracts user-agent exchanges from JSONL format\n3. **Embed** - Generates vector embeddings using Transformers.js (local, offline)\n4. **Index** - Stores in SQLite with sqlite-vec for fast similarity search\n5. **Search** - Semantic search using vector similarity or exact text matching\n\n## Excluding Conversations\n\nConversations containing this marker anywhere in their content will be archived but not indexed:\n\n```\n\u003cINSTRUCTIONS-TO-EPISODIC-MEMORY\u003eDO NOT INDEX THIS CHAT\u003c/INSTRUCTIONS-TO-EPISODIC-MEMORY\u003e\n```\n\n**Automatic exclusions:**\n- Conversations where Claude generates summaries (marker in system prompt)\n- Meta-conversations about conversation processing\n\n**Use cases:**\n- Sensitive work conversations\n- Tool invocation sessions (summarization, analysis)\n- Test or experimental sessions\n- Any conversation you don't want searchable\n\nThe marker can appear in any message (user or assistant) and excludes the entire conversation from the search index.\n\n## MCP Server\n\nWhen installed as a Claude Code plugin, episodic-memory provides an MCP (Model Context Protocol) server that exposes tools for searching and viewing conversations.\n\n### Available MCP Tools\n\n#### `episodic_memory_search`\n\nSearch indexed conversations using semantic similarity or exact text matching.\n\n**Single-concept search**: Pass a string query\n```json\n{\n  \"query\": \"React Router authentication\",\n  \"mode\": \"vector\",\n  \"limit\": 10\n}\n```\n\n**Multi-concept AND search**: Pass an array of concepts\n```json\n{\n  \"query\": [\"React Router\", \"authentication\", \"JWT\"],\n  \"limit\": 10\n}\n```\n\n**Parameters:**\n- `query` (string | string[]): Single string for regular search, or array of 2-5 strings for multi-concept AND search\n- `mode` ('vector' | 'text' | 'both'): Search mode for single-concept searches (default: 'both')\n- `limit` (number): Max results, 1-50 (default: 10)\n- `after` (string, optional): Only show conversations after YYYY-MM-DD\n- `before` (string, optional): Only show conversations before YYYY-MM-DD\n- `response_format` ('markdown' | 'json'): Output format (default: 'markdown')\n\n#### `episodic_memory_show`\n\nDisplay a full conversation in readable markdown format.\n\n```json\n{\n  \"path\": \"/path/to/conversation.jsonl\"\n}\n```\n\n**Parameters:**\n- `path` (string): Absolute path to the JSONL conversation file\n\n### Using the MCP Server Directly\n\nThe MCP server can also be used outside of Claude Code with any MCP-compatible client:\n\n```bash\n# Run the MCP server (stdio transport)\nepisodic-memory-mcp-server\n```\n\n## Development\n\n```bash\n# Install dependencies\nnpm install\n\n# Run tests\nnpm test\n\n# Build\nnpm run build\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fobra%2Fepisodic-memory","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fobra%2Fepisodic-memory","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fobra%2Fepisodic-memory/lists"}