EternalNight996/memory-eternal

English (default) · 简体中文

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, no outbound calls.
• ⭐ 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.

⚡ 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

📸 Screenshots

📚 Documentation & links

• Full manual (English) · 完整手册（中文）
• Private deployment (Docker / systemd)
• Changelog · Architecture
• Terminal plugin (dsh-tui) · Orca launcher · Cursor / VS Code extension
• Report a bug

💬 Community

Questions, ideas, or DSH plugin talk — join the groups:

QQ group	WeChat group

Buy the author a coffee (optional):

WeChat Pay	WeChat Reward

Sponsorship is optional; the plugin stays MIT and free. See SPONSOR.md.

📄 License

MIT — use it, self-host it, build on it.