# ๐Ÿง  memory-eternal โ€” A "second brain" for your AI

DSH plugin npm version GitHub stars license DSH Market listed

Auto-capture + visual library + knowledge graph (demo)

> **Auto-captures knowledge after every conversation and survives across sessions; recall fetches only the relevant chunks โ€” saves tokens, less noise.** > Fully self-built, zero third-party memory framework, no DSH source changes, one vault shared by every Agent, SQLite persistent storage, zero external dependencies.

โญ Star it if you like it!
DSH one-liner: dsh plugin --profile web add memory-eternal

Memory popup: knowledge cards / search / knowledge graph DSH Settings โ†’ Memory: all options Sidebar quick entry

--- ## ๐Ÿš€ Get Started in 5 Minutes ### ๐ŸŸฆ DeepSeek Harness (DSH) โ€” focus **Install** (dsh-desktop via DSH CLI, one command): ```bash # dsh-desktop (recommended): install via DSH CLI into the profile dsh plugin --profile web add memory-eternal # or update directly in the profile (pnpm workspace). Use pnpm โ€” `npm install` throws EUNSUPPORTEDPROTOCOL cd ~/.dsh/profiles/web && pnpm add memory-eternal@latest # right after a release, @latest can be held back by pnpm's minimum-release-age gate or a cached # packument (it silently stays on the old version): pin the version instead โ€” pnpm adds it to the # workspace's minimumReleaseAgeExclude automatically cd ~/.dsh/profiles/web && pnpm add memory-eternal@0.9.0 # verify the version, then restart dsh web node -e "console.log(require('memory-eternal/package.json').version)" ``` After **restarting dsh web**, three things are live immediately: | Effect | Where | |---|---| | Auto-capture of knowledge cards | Happens every turn, no action needed | | `memory_recall` tool | Agent calls it automatically when it needs history | | Visual UI | Sidebar bottom `Memory` button / Settings โ†’ Memory | **Entry**: The sidebar-footer `Memory` button opens the vault (its left rail includes Cards / Graph / Usage / **Audit Center** / Recycle Bin / **Memory Config**); "DSH Settings โ†’ Memory" is the pure config page. **UI language**: The whole UI is bilingual (English / ไธญๆ–‡) and follows **DSH Settings โ†’ Language** in real time โ€” Cards, Graph, Audit Center, card templates, config panel all included; the standalone web page follows the browser language. **Edit config**: Vault left rail "Memory Config" (or DSH Settings โ†’ Memory) โ†’ DSH memory config / cost control / auto-audit config / self-hosting โ€” just hit "Save Config". `autoWebMode` / `watchdogAutoSpawn` changes require a DSH restart. ### ๐ŸŸจ Claude Code ```bash npm i -g memory-eternal # installs CLI + MCP (auto-writes ~/.claude.json + SessionEnd hook) ``` Ready after install: say "recall ๆ•ฐๆฎๅบ“้€‰ๅž‹" in a session โ†’ auto-retrieves memory; on session end / before context compaction โ†’ auto-captures. ### ๐ŸŸง Codex CLI / Cursor ```bash npm i -g memory-eternal # auto-writes Codex config.toml / Cursor mcp.json ``` Restart the tool โ†’ MCP is in the list; just use: `็”จ memory_recall ๆŸฅไธ€ไธ‹้กน็›ฎๅŽ†ๅฒๅ†ณ็ญ–`. ### ๐ŸŸฉ Browser (no Agent needed) ```bash dsh-memory open # starts web + opens browser (default http://127.0.0.1:7999) ``` Stats / search / card grid (add-edit-merge-import-export) / knowledge graph โ€” all here. Same UI as the DSH embed; data stays in sync. > **zcode (Zhipu)**: no native MCP; bridge via [zcode-open-bridge](https://github.com/tizerluo/zcode-open-bridge) or use the CLI directly. --- ## ๐Ÿ“– Command Reference ```bash dsh-memory recall "database selection" # retrieve dsh-memory capture "important note..." # manual capture (- reads stdin) dsh-memory sweep ~/.claude/projects # mine existing sessions dsh-memory setup [--dry-run] # re-run / preview auto-mount (idempotent) dsh-memory mcp # MCP stdio (mount to any MCP client) dsh-memory serve [--port 7999] # run web in foreground dsh-memory open # ensure web alive + open browser dsh-memory watchdog [--port 7799] # watchdog keep-alive (standalone process) ``` When not running on DSH, the `dsh-memory` command comes from `npm i -g`. --- ## โš™๏ธ Self-hosting (plain words) Three concepts, don't mix them: - **How the web server stays alive** (`autoWebMode`) โ†’ `init`=pull once at DSH start (default); `interval`=DSH in-process timer probes & auto-restarts (0 extra memory); `manual`=fully manual, only from `dsh-memory open`. - **Watchdog process** (`watchdogAutoSpawn`, default on) โ†’ a **standalone** node process that can pull web up even after DSH exits (~+47 MB RAM). Only turn on for 7ร—24 keep-alive. - **Auto-mount MCP** (`autoMcpSetup`, default off) โ†’ whether to auto-write MCP into Claude Code/Codex/Cursor config. Off = don't touch your machine config; run `dsh-memory setup` manually when needed. **Change these**: Vault left rail "Memory Config" (or DSH Settings โ†’ Memory) โ†’ edit the table and save; `autoWebMode` / `watchdogAutoSpawn` need a DSH restart. **MCP is a protocol, not a resident service**: the agent spawns it per session and exits when done โ€” no "auto-start on boot" concept. ### Three deployment intensities | Scenario | Config | Memory | |---|---|---| | Personal dev (default) | `autoWebMode=init` + `watchdogAutoSpawn=off` | web 47 MB | | Resident 7ร—24 | `watchdogAutoSpawn=on` | web + watchdog 47+47 MB | | True boot auto-start (no DSH) | Windows Task Scheduler runs `dsh-memory watchdog --port 7799 --interval 5000 --max-restart 10` | same | --- ## โš™๏ธ Memory Config (plain words) > All settings live in the **vault left rail "Memory Config"** (or DSH Settings โ†’ Memory) โ€” edit and hit "Save". Here's the full page (plugin info / Agent MCP mount status / auto-audit config):

Memory config page

### 1. Most used | Setting | Default | In plain words | |---|---|---| | Auto capture | on | auto-store useful content as cards after each turn | | Auto recall | on | AI auto-queries memory when it needs history | | Vault dir | `~/.dsh/memory-vault` | where memory lives, plain Markdown & git-able | ### 2. Save money (important) | Setting | Default | In plain words | |---|---|---| | **Distill cards** | on | **compress** a conversation into a sharp card (calls AI, costs money). **Off = store raw text, zero cost** | | **Dedup feeds AI** | on | judge if new content is a duplicate (calls AI). **Off = simple dedup**, saves one AI call | | Distill output cap | 900 | max chars per compress, bigger = sharper but pricier | | Recall min score | 2 | how "close" a match must be to return; bigger = sharper but leaks more (cheaper) | | Min capture chars | 200 | too-short chats aren't stored (avoids small-talk waste) | | Daily quota | 60 | max cards per day, prevents AI burning money | ### 3. How the service runs | Setting | Default | In plain words | |---|---|---| | Keep-alive `autoWebMode` | init | `init`=open web once at DSH start; `interval`=periodically check & restart if dead; `manual`=fully manual | | Watchdog `watchdogAutoSpawn` | on | a **standalone process** keeps web alive (+47 MB). Personal use can turn off | | Auto-mount MCP `autoMcpSetup` | off | **lets Claude Code / Codex / Cursor use your memory**. On = auto-configures them; Off = never touches your config, run `dsh-memory setup` manually | > ๐Ÿ’ฐ **To save money**: turn `Distill cards` off, lower `Distill output cap`, raise `Recall min score`. ### ๐ŸŽฏ One-click presets Top of the config page: **๐ŸŸข A Light / ๐Ÿ’ฐ B Budget / โญ C Premium** โ€” click to fill, then Save: | Plan | Scenario | Keep-alive | Watchdog | Distill | Distill cap | Recall min | Memory | LLM cost | |---|---|---|---|---|---|---|---|---| | ๐ŸŸข **A Light** | Personal dev (default) | init | off | on | 900 | 2 | ~47 MB | normal | | ๐Ÿ’ฐ **B Budget** | Tight budget / many Agents | init | off | **off** | 500 | 3 | ~47 MB | **~0** | | โญ **C Premium** | Long projects / teams | interval | **on** | on | 1200 | 1 | ~94 MB | high | --- ## ๐Ÿ”” Capture Log & Failure Alerts Auto-capture is a silent background pipeline: when it broke, the only symptom used to be "no new cards" with no visible cause. Since v0.9.0 it speaks up. - **Capture log**: Settings โ†’ Memory โ†’ Usage / Today shows the last 100 run entries: `๐Ÿš€ boot` / `๐Ÿ‘‚ session attached (which event API + event count)` / `โœ… card created` / `โž• update appended` / `โญ skipped (reason)` / `โŒ failed (reason)`. - **Active alerts**: any failure turns the strip red at the top of the memory library *and* injects "auto-capture failed + reason" into the agent context, so the agent tells you in its first sentence โ€” no need to dig through logs. - **Stall watchdog**: if turns start but no turn-stopping event arrives for 15 minutes (e.g. DSH renamed the event), a 10-minute sweep reports it. - **Self-adapting event API**: the session event API is detected automatically (`ownEvents()` โ†’ `snapshotEvents()` โ†’ `events`), so a DSH upgrade that changes the API can no longer silently break capture. --- ## ๐Ÿ›ก๏ธ Audit Center & Recycle Bin > **Agents cannot approve on your behalf (since v0.9.1).** Whenever audit is active, the plugin injects a red line into the agent context: new cards stay `pending`, and calling the `approve`/`reject` endpoints (or any equivalent bypass) is forbidden. The decision is always yours. New cards go to the **Audit Center** (`pending`) by default and enter the main vault only after you approve them; rejected ones move to "Rejected", where you can restore or delete to the recycle bin. Cards matching an exemption (audit mode = skip all / exempt agents / exempt kinds) go straight in; recycle-bin cards are recoverable within 30 days, then auto-purged.

Audit Center

- **Pending / Rejected** tabs, filtered by type / date / agent; select all and approve / reject / delete-to-recycle in one click. - Rules in "Memory Config โ†’ Auto-audit config": `audit mode` (audit all / skip all) + `exempt agents` + `exempt kinds` + `recycle retention days`. ### ๐Ÿฅ‡ Why the audit system is more reliable (vs other memory products) Most memory products (mem0 / Zep / agentmemoryโ€ฆ) auto-ingest **everything** the moment a conversation ends, good or bad โ€” noise, wrong facts, and sensitive content all go in and get recalled later, **polluting context and amplifying hallucinations**. memory-eternal uses **human-in-the-loop auditing** โ€” only trusted content enters the main vault: | Dimension | Other memory products | memory-eternal audit system | |---|---|---| | Ingest | Auto-ingest all, no gate | New cards first enter the **Audit Center (`pending`)**, approved before entering the vault | | Quality | No filtering of noise/errors | Only cards you've confirmed โ†’ more accurate recall, less noise | | Traceability | No source/audit trail | Every card carries `submittedBy` author + `pending/approved/rejected` state | | No-friction | โ€” | Exempt agents / exempt kinds hit โ†’ trusted cards go straight in, zero wait | | Safety | Delete = gone forever | Recycle-bin soft delete, recoverable within 30 days | --- ## ๐Ÿงฌ Why Fully Self-built Most memory solutions lean on third-party frameworks / spin up an MCP service / lock memory in a private store. This plugin builds the skeleton itself โ€” **zero third-party runtime deps**, logic readable line by line: | Module | Self-built | Replaces | |---|---|---| | Dedup | lexical Jaccard bigram (0.62) + semantic dedup | duplicate-card prevention | | Retrieval | CJK-aware: Chinese whole-word + char bigram | no full-text search engine needed | | Graph | force-directed + `[[wikilink]]`/shared-tag edges | see knowledge links at a glance | | Storage | plain `.md` with frontmatter | not locked in, readable, git-able, any tool can read | > Same direction as popular projects (summarizeโ†’storeโ†’recall), but positioned differently: **local, self-built, zero-dep, readable & controllable**. If you already use mem0/Zep etc., just layer this as a "local persistent memory base". --- ## ๐Ÿ›  Development / Test ```bash npm i npm test # unit tests: vault dedup/retrieval/graph + capture pipeline + API shapes npm run build # builds lib/client.js (DSH embed) + web/app.js (standalone web bundle) ``` --- ## ๐Ÿ“‹ Changelog | Version | Date | Highlights | |---|---|---| | **v0.9.3** | 2026-09-12 | **Fixed the blank memory page ("no UI")**: v0.9.1 placed the infinite-scroll `useEffect` **before** the `loadCards` definition โ€” React evaluates the dependency array during render, hitting a TDZ error (`Cannot access 'loadCards' before initialization`) that **crashed the whole memory page on first render**. It now comes after the definition. Added a **render smoke test** (`tests/ssr.test.mjs`: renders the built bundle through all four entry points โ€” cards / settings / usage / graph โ€” wired into `npm test`) so "green build, blank page" bugs cannot ship again | | **v0.9.2** | 2026-09-12 | **Log visibility + false-alarm fix**: the capture log is now **persisted to disk** (`~/.dsh/memory-eternal-capture.jsonl`, last 500 entries) โ€” the standalone web page no longer says "log only available inside the DSH host" but shows the records, and history survives a host restart (read back on boot); fixed **stall-detector false alarms flooding the panel** (mismatched turn counters are normal: sub-agent turns and cancelled turns emit no `turn-stopping`; it now requires "turns running **and** no capture activity for 15 minutes" to alert once, and the alarm clears as soon as activity resumes โ€” no more one `fail` line every 10 minutes permanently turning health red); when distillation returns nothing / unparseable JSON the content is **saved as a raw card instead of being dropped** | | **v0.9.1** | 2026-09-12 | **Performance & UX batch**: memory page loads lazily per view (opening Settings no longer drags in 250KB of cards + 890KB of graph; first paint needs ~0.5KB); graph generation **3232ms โ†’ 43ms** (bigram sets computed once + lossless mathematical-bound pruning + tag inverted index) plus a server-side cache with **fingerprint invalidation** (write/audit/delete rebuilds immediately, no stale reads); site-wide **brotli q5** (graph 877KB โ†’ **54KB**, 34% smaller than gzip; cards 246KB โ†’ 83KB โ†’ 20KB with br) and large responses compressed with both br and gzip keeping the smaller, so no response is ever worse than gzip; `/cards` gained **real pagination** (offset/limit/total + server-side title sort, globally ordered across pages) loading 100 cards first and fetching more on scroll; the "Agent cards" panel in Usage/Today filters by agent server-side (30 rows); **audit red line**: the plugin injects "never call approve/reject on the user's behalf" into the agent context; the watchdog now **reaps redundant instances on fallback ports** (a duplicate web process holding 76MB was reaped in testing) | | **v0.9.0** | 2026-09-12 | **Fixed silent auto-capture death (6 days without a single card)**: after a DSH upgrade the session event API moved from `events` to `ownEvents()/snapshotEvents()`; the listener read nothing, returned silently and left no trace โ€” now it tries `ownEvents()` โ†’ `snapshotEvents()` โ†’ `events` and logs a per-session attach entry. Daily quota now counts **real writes only** (previously every "not worth saving" verdict burned quota, exhausting the 24h budget after 40 attempts); `captureCooldownMs` actually applies; a single capture input is tail-capped at 20k chars. New **capture log** panel and **active failure alerts** (red strip + agent-context injection + turn-stopping stall sweep). Removed the automatic "Daily review" digest (timer / `/todayBrief` route / UI button). | | **v0.8.0** | 2026-09-06 | **Full UI i18n**: follows the DSH system language live (zh/en) across cards, graph, audit center, config panel and new-card templates; SQLite EBUSY fix for the Windows test suite | | **v0.3.1** | 2026-09-03 | Knowledge graph loads on demand (fetch on open, unregister on close) | | **v0.3.0** | 2026-09-03 | **SQLite storage layer** (`node:sqlite`, zero deps) + DB-level audit guard `enforceAudit()` + `audit_log` table + automatic `.md` migration | | v0.2.0 | 2026-09-03 | Recall with body text (`search()` returns the `excerpt` field) | | v0.1.2 | 2026-09-03 | Audit guard hardening (`writeCard` defaults to `pending`, `mergeCards` goes through audit) | | v0.1.1 | 2026-09-03 | Recall body fix (`excerpt` field + body logic) | | v0.1.0 | 2026-08-31 | First release: auto capture + auto recall + graphical knowledge base + knowledge graph + audit center + recycle bin | --- ## ๐Ÿ“„ License MIT --- > **Make your AI truly remember: dialogue auto-captured, knowledge at your fingertips.** โญ Star it if you like, Let's make AI not forget. > > ไธญๆ–‡ README: [README.md](README.md)