Eidetic

Persistent memory for Claude Code. Store knowledge, recall by meaning, pick up where you left off.

Quick Start

Set your OpenAI API key, then install the plugin inside Claude Code:

export OPENAI_API_KEY=sk-...

/plugin marketplace add tai-io/eidetic
/plugin install eidetic@tai-io

add_memory(
  query="error handling conventions",
  facts=[
    { fact: "Use typed errors at service boundaries", kind: "convention" },
    { fact: "Never use bare try/catch without re-throwing", kind: "constraint" }
  ]
)

search_memory("how do we handle errors")

That's it. Memories persist across sessions, projects, and context compactions.

What It Does

Persistent Memory

Claude forgets everything between sessions. Eidetic fixes that. add_memory stores structured facts grouped under the query that prompted them. Facts are deduplicated semantically, so storing the same knowledge twice just merges it.

search_memory retrieves relevant knowledge by meaning. Ask "how does auth work" and get back every decision, convention, and constraint you've stored about authentication, ranked by relevance.

Five kinds of knowledge: fact, decision, convention, constraint, intent.

Session Continuity

When a session ends or context compacts mid-conversation, Eidetic automatically writes a structured note capturing what happened: files changed, decisions made, commands run, open questions. Start a new session with /catchup and pick up exactly where you left off.

Automatic Extraction

Session hooks watch your conversations and extract durable knowledge (decisions, conventions, constraints) into a buffer. The buffer pipeline consolidates extractions via LLM and stores them as searchable memories. No manual add_memory calls needed for the most important stuff.

Installation

Plugin (recommended)

Inside a Claude Code session:

/plugin marketplace add tai-io/eidetic
/plugin install eidetic@tai-io

The plugin starts the MCP server, installs skills, and configures hooks automatically.

npx (manual MCP config)

Add to your .mcp.json:

{
  "mcpServers": {
    "eidetic": {
      "command": "npx",
      "args": ["-y", "@tai-io/eidetic"],
      "env": {
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

Global install

npm install -g @tai-io/eidetic
claude mcp add -s user -e "OPENAI_API_KEY=$OPENAI_API_KEY" -- eidetic npx @tai-io/eidetic

From source

git clone https://github.com/tai-io/eidetic
cd eidetic
npm install && npm run build && npm start

Requirements

• Node.js >= 20
• OPENAI_API_KEY for embeddings

Configuration

Set your OpenAI API key in your shell profile:

export OPENAI_API_KEY=sk-...   # macOS / Linux
setx OPENAI_API_KEY sk-...     # Windows

| Variable | Default | Description | |---|---|---| | OPENAI_API_KEY | (required) | OpenAI API key for embeddings | | EMBEDDING_MODEL | text-embedding-3-small | Embedding model name | | EMBEDDING_BATCH_SIZE | 100 | Batch size for embedding requests (1-2048) | | OPENAI_BASE_URL | (none) | Custom OpenAI-compatible endpoint | | EIDETIC_DATA_DIR | ~/.eidetic/ | Data root for memory DB and session notes |

| Tool | Description | |---|---| | add_memory | Store facts grouped under a query. Deduplicates semantically. | | search_memory | Search memories by meaning. Returns ranked results with facts. | | list_memories | List all memories, filterable by kind or project. | | delete_memory | Delete a memory group by ID. | | memory_history | View change history for a memory. |

| Skill | Description | |---|---| | /catchup | Reconstruct session context from notes and memories | | /wrapup | Extract decisions and next actions, persist to notes and memories |

Development

npm install && npm run build    # install and build
npm run dev                     # watch mode
npm test                        # unit tests (no external services)
npm run lint                    # eslint

Commit format: type(scope): description / Types: feat, fix, docs, refactor, test, chore

License

MIT