elephia 🐘

git for your AI's context — an elephant never forgets. A local-first, deterministic memory engine for Claude Desktop, Claude Code, Codex, and Cursor — served over MCP.

Every conversation turn is committed to an append-only journal. Durable facts (decisions, corrections, preferences) merge into a versioned memory wiki. Each new prompt gets a branch: a compact, token-budgeted context patch compiled from your whole history — with full provenance, per-item salience scores, and a token meter that shows exactly what you saved.

No embeddings API. No cloud. No LLM in the loop. The compiler is mechanical and deterministic: the same history and prompt always produce the same context, and every selection or exclusion has an inspectable reason.

$ elephia branch "What database does Atlas use?"
Context Merge Patch:
- recurring_topics: atlas(20), postgresql(7), dashboard(4)
Selected Context:
- [wiki:Atlas Memory] wiki; score=0.636; Atlas Memory - correction: use MySQL.
- [event:demo_00022] event; score=0.623; Recorded Atlas API limits: 100 rps/tenant ...
Avoid Stale/Superseded:
- event:demo_00003 superseded_by event:demo_00005

-- 299 tokens (budget 300) | full history would be 670 tokens | saved 371 (55%)

Install

pip install elephia          # or: pipx install elephia / uv tool install elephia
pip install "elephia[tokens]"  # + tiktoken for exact token counts (recommended)

Or from source: git clone https://github.com/elephia/elephia && pip install -e ./elephia

Quick start (60 seconds)

elephia init        # create a .elephia/ store here (like git init)
elephia demo        # optional: seed sample data
elephia branch "What database does Atlas use?"           # compile a context patch
elephia branch "What database does Atlas use?" --explain # why each item was selected/excluded
elephia stats       # token meter: patch tokens vs. tokens saved

Prefer buttons to commands?

elephia ui          # opens a private dashboard in your browser

A local point-and-click view of everything: what your AI knows, facts waiting for your approval (approve/reject), a "teach it something" box, search with one-click "mark outdated", and a live preview of the exact context any question would get — with the token savings metered. Binds to 127.0.0.1 only; every request requires a per-session token, so nothing on your network (or any website you visit) can reach your store.

Hook it into your AI apps

One command per client — it edits the client's config for you (with a .bak backup):

elephia install claude-code      # writes .mcp.json in the current project
elephia install claude-desktop   # edits claude_desktop_config.json
elephia install codex            # adds [mcp_servers.elephia] to ~/.codex/config.toml
elephia install cursor           # edits ~/.cursor/mcp.json
elephia install print            # just show all config snippets

Restart the client. Then ask Claude (or Codex):

"Use prepare_context to load what you know about this project." "Remember that we deploy on Fridays." "Show me the merge log — what have you saved about me?" "Why didn't you remember X? Explain the selection."

What the model sees (MCP tools)

The git mental model

Store resolution is git-style too: --store flag → CONTEXTGIT_DIR env var → nearest .elephia/ walking up from the working directory → global ~/.elephia/store.

Why deterministic?

Memory systems that summarize with an LLM are unauditable: you can't know why something was remembered, forgotten, or silently rewritten. elephia's compiler is a mechanical scoring function (frequency, recency, query relevance via BM25, correction priority, source confidence, open-loop bonus, token cost, staleness penalty). That means:

• Reproducible — same store + same prompt = same context, byte for byte.
• Explainable — --explain shows each item's score components and exclusion reasons.
• Correction-safe — "use MySQL instead of PostgreSQL" supersedes the old fact; stale items are excluded and listed under "Avoid Stale/Superseded" so the model doesn't relearn them.
• Auditable — every memory mutation is in an append-only log with before/after state hashes.

Token tracking

Every compilation appends a row to usage.jsonl: patch tokens, what full history would have cost, tokens saved. Counting uses tiktoken when installed (o200k_base), with an honest fallback_estimate label otherwise.

elephia stats
#                 compilations  patch tokens  saved tokens   savings
# all time                  14          4186          21340    63.1%

Storage format (yours, forever)

Plain JSONL in .elephia/ — no database, no lock-in:

events.jsonl          append-only conversation journal
wiki_versions.jsonl   every version of every memory page
mutations.jsonl       append-only merge log (save / promote / mark_stale / reject)
audit.jsonl           decision audit with state hashes
pending.json          merge candidates awaiting review
usage.jsonl           token meter ledger

elephia export dumps a single JSON snapshot.

Development

pip install -e ".[dev,tokens]"
pytest

The engine (deterministic compiler, BM25 retrieval, versioned store) is benchmarked against eager/full-history baselines on contamination, staleness, and recall metrics in a separate research harness.

Known limitations

elephia is young (v0.1.x, beta). Today:

• One writer per store at a time. There's no file lock yet, so two clients writing the same store at the same moment can collide. Use per-project stores (the default) and avoid hammering one store from several apps at once.
• Best for small/medium stores. Context compilation stays interactive up to roughly 500 turns per store; very large stores get slow. Keep stores per-project and archive occasionally.
• Keep a backup. elephia export writes a JSON snapshot. elephia now skips a torn line rather than failing the whole store, but a periodic export is cheap insurance against a crash mid-write.
• Retrieval is lexical (BM25), not semantic. It finds notes by shared words, not meaning — treat the served context as a recall aid the model should sanity-check, not gospel.

These are tracked on the roadmap.

License

Apache-2.0