elephia

# elephia 🐘

<!-- mcp-name: io.github.elephia/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

```bash
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)

```bash
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?

```bash
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):

```bash
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)

| Tool | What it does |
|---|---|
| `prepare_context` | Compile a token-budgeted context patch relevant to the prompt, with token accounting |
| `commit_turn` | Journal a finished turn; durable phrasing auto-merges into the wiki |
| `remember` / `mark_stale` | Explicitly save a fact / retire an outdated one |
| `search_context` | BM25 search over all events + wiki pages |
| `context_log` / `show_context` | Recent events; any record in full by ref |
| `full_context` | Page through the complete raw history (token counts included) |
| `explain_selection` | Per-item salience scores + exclusion reasons for a prompt |
| `merge_log` / `resolve_pending` | Merge history; approve/reject pending merges |
| `context_stats` | Token meter: compilations, tokens served, tokens saved |

## The git mental model

| git | elephia |
|---|---|
| repository | `.elephia/` store (per project, or `~/.elephia/store` global) |
| commit | journaled conversation turn (`commit_turn`, append-only `events.jsonl`) |
| branch | compiled context patch for the current prompt (`elephia branch`) |
| merge | durable fact saved to the versioned wiki (`merge_log`, `mutations.jsonl`) |
| staging area | pending-merge queue (`elephia pending list / approve / reject`) |
| log / show | `elephia log`, `elephia show event:<id> | wiki:<title> | mut:<id>` |
| blame | provenance: every wiki claim links to the source events that produced it |

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.

```bash
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

```bash
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