🧠 memory-eternal — a second brain for your AI

_{▲ 20-second tour — review queue · token ledger · knowledge graph · live demo}

Your AI forgets every session. Give it a memory it can trust.

> Local-first, review-gated, measurable — one SQLite vault shared by DSH, Claude Code, Codex, Cursor and any MCP client.

🔍 Review before it counts — new cards wait in a review queue; approve or reject from the Web UI or terminal; every change is written to an immutable audit log.
🧾 Token ledger — see how much recall injected, how many distillation calls ran, and how often recall was actually useful.
🏠 Local-first, no cloud — SQLite + Markdown on your own disk. No third-party memory framework, no account. Memory data never leaves the machine; only the News page fetches public RSS / Hacker News on demand (titles, excerpts and outbound links only).
⭐ Core memory — promote approved cards to always-on memory; every session gets them automatically, and the review queue still decides what qualifies.
🧭 Reader & layout — clickable table of contents in the card reader, plus a compact / normal / large layout setting for the whole memory UI.

⭐ If it saves you from explaining the same context again, a star helps a lot.
_{DSH one-liner: dsh plugin --profile desktop add memory-eternal}

⚡ Quick start

DeepSeek Harness (desktop / web)

dsh plugin --profile desktop add memory-eternal
reopen DSH → sidebar "Memory"

Claude Code, Codex or Cursor — same vault via MCP

npm i -g memory-eternal
dsh-memory connect claude    # or: codex / cursor

Any MCP client

npx -y -p memory-eternal dsh-memory mcp

Browser or terminal

dsh-memory open              # http://127.0.0.1:7999
npx -y -p memory-eternal dsh-memory tui   # live queue in the terminal

🧾 Does it actually save tokens?

Most memory products say they save tokens. We think you should check. The plugin ships a built-in memory ledger (Runtime status → Memory ledger) that records:

| Recorded | What it means | |---|---| | recall: hits + injected characters | how much memory actually entered the context | | capture: LLM calls + input/output characters | what distillation cost you | | usefulness: useful / not-useful feedback | whether recalled memories actually helped |

The honest math:

net benefit ≈ avoided context cost − (injected characters + distillation calls × price)

| Scenario | You pay | You avoid | |---|---|---| | Multi-session project with decisions and pitfalls | ~0.6–0.9k tokens per recall | re-explaining context (~1.5–3k) or re-reading files (3–6k) | | One-off question, low hit rate | recall injection | usually nothing |

Illustrative numbers, not a benchmark — measure your own with the ledger. If recall usefulness stays below ~60%, tune it down (fewer results, shorter summaries) or turn memory off.

🛡️ Review first, prove later

A memory system that silently ingests everything will eventually recall a wrong fact as truth. memory-eternal defaults to review-before-commit:

new cards land in a pending queue; nothing enters the main vault until a human approves it;
approve, reject or bulk-process from the Web UI, the terminal TUI, or the CLI;
every status change is appended to an immutable audit log (who / what / when / why) — enforced at the SQLite layer, not by convention;
agents can read and propose, but cannot approve their own cards;
deleted cards go to a recycle bin (30 days by default).

⭐ Core memory

Not everything should be injected into every session. Core memory is the small, explicit set of rules and preferences that must always win:

any approved card can be promoted from the reader or card list;
auto-capture may suggest core only for explicit long-term preferences / hard constraints, and core candidates always stay pending for review;
approved core cards are injected into the system prompt of every session — no memory_recall call needed;
set a card limit and character budget in Settings → Memory → Core memory;
in the knowledge graph, core nodes are orange diamonds with a ★;
never store secrets or API keys in a core card; keep only a pointer to the credential directory.

🎛 Reader & layout

click any heading in the reader's table of contents to smoothly scroll to that section;
Settings → Memory → Layout size offers compact / normal / large for the whole UI; it only affects display.

🧩 One vault, every agent

| Entry | What you get | |---|---| | DSH desktop / web | embedded memory UI: review, graph, config, ledger | | Claude Code / Codex / Cursor | MCP server, same local vault, dsh-memory connect | | Any MCP client | npx -y -p memory-eternal dsh-memory mcp | | Terminal | dsh-memory tui — live queue, select-all, batch approve/reject, long-form reader | | Browser | dsh-memory open → http://127.0.0.1:7999 |