elepha

Overview

elepha reads eligible Claude Code and Codex session files, plus the local OpenCode session database, indexes sessions from approved projects in one encrypted SQLite database, and exposes past context through a read-only MCP server and elepha: commands in AI chat.

It does not modify source transcripts or repositories, send messages, or act on the user's behalf. Transcript content and derived text are treated as inert data, never as code, commands, or paths to execute. Capture, local search, and recall do not require an AI provider key.

Get started

npm install -g elepha
elepha install
elepha init

Codex requires manual approval of elepha's hooks through /hooks and may ask again after a hook changes.

Full walkthrough: getting-started guide.

Supported tools and platforms

elepha supports:

• Claude Code CLI & desktop
• Codex CLI & desktop
• OpenCode

All supported tools use the same local memory database.

It runs on macOS, Linux, and Windows through WSL, on Node.js 22.15+. Native Windows is not supported; see the getting-started guide for exact requirements.

How it works

1. Capture: A background service reads supported local session sources under approved project roots.
2. Index: Session metadata, summaries, and filtered durable copies are stored in the encrypted local database.
3. Recall: A read-only MCP server and elepha: commands surface past context in chat. Ask in plain language, or find and reopen sessions with elepha:query / elepha:resume / elepha:last.

Search uses stored titles, first prompts, rollups, and the filtered local full-text index where a durable copy is available. Session recall renders filtered content from complete retained database copies for Claude Code and Codex. Missing, stale or incompatible copies stay explicit gaps; ordinary reads never reopen their provider transcripts or trigger capture or repair. Individually current interactions and stored summaries may still be returned with their limited scope. OpenCode keeps its legacy source rendering. Results are bounded and report when older turns were omitted.

Recall in chat: ask in plain language

No keywords needed. When elepha's MCP tools are connected, ask in natural language and it answers with the reasoning: what was decided, why, and what is still open, naming the project and session it came from.

do you remember why we moved the purchase button into a modal?

To find and reopen a session, the elepha: commands work in Claude Code, Codex, and OpenCode chat. Full guide: docs/commands-in-ai-chat.md.

Command	What it does
elepha:query <text>	Find sessions from plain text across all approved projects.
elepha:query:here <text>	Same, current project only.
elepha:last	Serve the newest turns from the most recent session.
elepha:list[:<n>]	List recent sessions, numbered (up to 100).
elepha:resume:<n>	Load a session to continue it; the model presents a recap.
elepha:info	Show status: sessions, capture, last session, and when a new version is available.

Storage

elepha stores session metadata and summaries. For Claude Code and Codex it also keeps its own filtered copy of each newly captured turn inside the encrypted database, automatically and with no extra setting: sanitized user prompts, assistant responses, and path-bearing tool-call metadata. Raw JSONL, thinking, tool output, fetched content, and raw tool arguments are excluded. That copy:

• survives the original transcript being deleted, so it can remain the only record;
• enables local full-text search of past content with no AI provider key;
• travels inside encrypted backups and project exports.

All of elepha's memory shares a fixed 5 GB capacity; at capacity the oldest whole sessions are removed after an encrypted backup, and elepha status lists them. The legacy durable-capture setting (off by default) enables new OpenCode copies:

elepha config set durable-capture true
elepha config set durable-capture false

See protecting and recovering memory.

Privacy and consent

The encrypted database, search index, and recall service are local.

• Only projects and workspace folders you approve are eligible for capture.
• Original session files are never modified.
• The whole database is encrypted. Its key is stored in the OS secret store, or in a private key file where no usable secret store exists.
• Paranoid mode gates reads while capture continues. It protects a stolen or copied database and memory on a shared unlocked machine, not malware already running as your user.
• Revoking consent stops capture and hides retained memory for that scope without deleting it. Purge deletes selected memory and prevents its source transcript from being re-ingested.
• Memory lives at $ELEPHA_HOME/elepha.db, or ~/.elepha/elepha.db by default. Current encrypted backups require the same installation key.

Documentation

• Getting started
• In-AI-chat command index
• CLI command index
• Choosing what elepha may remember
• Controlling capture
• Configuration
• Protecting and recovering memory
• Deleting memory
• Updating and maintenance
• Troubleshooting

License and links

elepha is open-source software licensed under the Mozilla Public License 2.0 (MPL-2.0).

• Security policy
• Contributing guide