PerryLink/dsh-memento

dsh-memento

• 1024 store channel: npm i -g dsh1024 once, then dsh1024 plugin --profile web add dsh-memento (counts toward the deepseek1024.com install ranking).

Bounded, layered, approval-gated, auditable cross-session memory for DeepSeek Harness.

*A typed ctx.memory seam, a write-approval gate no model path can bypass, and an audit trail you can rebuild — from the approval pair plus the plugin's own audit table, with the session-log gap named out loud.*

English · 简体中文 · Español · Português · हिन्दी

dsh plugin --profile <name> add dsh-memento

📖 Ecosystem knowledge base — measured data, not marketing: plugin development guide · plugin-selection data · maintenance criteria.

Install & uninstall

• git channel (latest main): dsh plugin --profile web add git+https://github.com/PerryLink/dsh-memento.git.
• npm channel (published releases): dsh plugin --profile web add dsh-memento.
• tarball channel: npm pack in this repo, then dsh plugin --profile web add ./dsh-memento-.tgz.
• uninstall: dsh plugin --profile web remove dsh-memento (the memory database and session logs are kept).

⭐ 如果它帮到了你

这个插件是 DSH 插件家族的一员（95 个，全部 Apache-2.0）。如果你在用，给个 star —— 它不会解锁任何功能，但会让下一个人在搜索里更容易找到它。

*English:* part of a 95 plugin family for DeepSeek Harness. If it is useful, a star helps the next person find it — nothing is gated behind it.

What is dsh-memento?

Bounded, layered, approval-gated, auditable cross-session memory for DeepSeek Harness.

A typed ctx.memory seam, a write-approval gate no model path can bypass, and an audit trail you can rebuild — from the approval pair plus the plugin's own audit table, with the session-log gap named out loud.

*Workflow overview: install → open panel → act. The examples below use the real command surface.*

*▶ 2 min 23 s narrated walkthrough — the thumbnail opens the MP4 file; if it does not play on the page, use *Download raw file* there (MP4, 1.87 MB · direct download). GitHub strips `` tags from README files, so the video is a file to open rather than something embedded inline.*

Compatibility

Surface · Status Harness · DeepSeek Harness dsh-v0.2.1-alpha.2 (adapted 2026-10-12; 0.2.1-alpha.1 since 2026-10-04): the 0.1.7 line replaced the whole settings registration surface (installSettingsSection / SettingsProvider.installSection / SettingsNamespace / SettingsScope) with live Config forms, so both halves follow the new contract — a form's namespace is the profile entry id (memento), its editable fields are the .volatile() ones, and an accepted edit is committed into the running plugin instead of remounting it. The browser half reads that form through ctx.configForms.get(entryId) (the ctx.settingsScope service is gone). Both halves keep their installSection / settingsScope branches for the 0.1.2-rc.1, 0.1.5-alpha.1 and 0.1.6-0 lines the peer range still advertises, and the new >=0.1.7-0 /*-namespaced appendPluginRecord writer, but the host's own packages/core/session/README.md forbids out-of-repo callers and the mandatory plugin: prefix cannot express memory/*, so this package does not adopt it. Node · ^22.19.0 · >=24.0.0 Platforms · Windows / macOS / Linux (pure host; no native code, no network) Model · Any

What you get

dsh-memento is a capability seam, not another memory warehouse: a typed ctx.memory service, a local SQLite provider (node:sqlite, WAL, 0600, at $DSH_HOME/dsh-memento/memory.db), and its consumers — the memory tool and a frozen snapshot injected into the system prompt.

• The approval gate cannot be bypassed. Every write path (add / replace / remove / seed) is forced through the approval waterfall inside the service, not in the tool layer. writePolicy: ask | auto | off is model-invisible configuration; replace / remove / consolidate carry the full text of the entries they change in the approval payload, and a denied write still lands a *-denied audit row.
• Model-visible ⟺ logged. The injected snapshot lands verbatim in system/message; every write is reconstructable from approval/asked + approval/decided + the plugin's own audit table.
• Bounded and honest. Hard per-track/per-layer character budgets (default user 2000 / agent 4000). A full store fails with a structured error (usage + limit) — never truncated, never auto-compacted.
• The audit gap is visible. /memory audit lists the plugin audit table and appends one line when the session-log side is not written: this harness does not know the memory/* session event types, and appending unknown types would make the session unloadable, so writes are audited through approval/asked + approval/decided and the plugin's table instead. The gate is adaptive — the line disappears on its own once the host knows those types.

Two tracks × two layers × per-agent key: a user track (facts about the user) and an agent track (environment facts and conventions), each split into user-global and workspace layers, isolated per agentPreset. The snapshot is frozen once per session at first prompt assembly and never changes mid-session.

Quick start

dsh plugin --profile web add github:PerryLink/dsh-memento

# 1. install the bundle into your profile
dsh plugin --profile web add github:PerryLink/dsh-memento

# or from npm (published releases)
dsh plugin --profile web add dsh-memento

# 2. restart and verify the row
dsh --profile web --dump-config | grep -A3 'id: memento'

Examples

These are the plugin's real entry points; install once, then call one.

Detailed example

Command

~~~sh memory_stats ~~~

Input

~~~json {"jsonrpc":"2.0","id":7,"method":"tools/call","params":{"name":"memory_stats","arguments":{}}} ~~~

Output

~~~text { "total": 3, "namespaces": [ { "track": "agent", "scope": "user-global", "count": 1 }, { "track": "agent", "scope": "workspace", "count": 1 }, { "track": "user", "scope": "workspace", "count": 1 } ] } ~~~

*Observed from test/mcp.test.mjs:108-118 (fixture seed at 21-27); README.md:160-176*

Failure branch

Input

~~~text {"jsonrpc":"2.0","id":10,"method":"tools/call","params":{"name":"memory_search","arguments":{}}} ~~~

Output

~~~text {"jsonrpc":"2.0","id":10,"result":{"content":[{"type":"text","text":"invalid arguments: query must be a non-empty string"}],"isError":true}} ~~~

*Observed from plugins/dsh-memento/lib/mcp.mjs:188; plugins/dsh-memento/test/mcp.test.mjs:126-127; reproduced via plugins/dsh-memento/bin/mcp-server.mjs*

Brief examples

• /memory

Configuration

All tunables are Schemastery Config fields (changeable from cordis.yml). Invalid values fail loudly at load. Override under the memento row.

Settings panel. On the 0.1.7 line the plugin's own Config is its settings page: the form's namespace is the profile entry id (memento — the id: of this bundle's row), the editable fields are exactly the ones the plugin declares .volatile() (every key below except enabled), and an accepted edit is merged into the profile's plugin row and committed into the running plugin — no file editing, no restart. Nearly everything applies live (write policies, language, budgets, limits, proposals, panel, dbPath / auditRetentionDays via a store reopen, retrieval.vector via a retriever swap); what a plugin registers at load time (snapshotOrder, tool descriptions) is re-read on reload, and the page marks those fields. Numeric bounds are declared in the schema as well, so an out-of-range edit is refused at write time instead of leaving an unusable config behind. On the older lines (0.1.2-rc.1, 0.1.5-alpha.1, 0.1.6-0) the same card edits the dsh-memento settings namespace exactly as before; with no settings service at all, everything falls back to the composed cordis config. The floating panel button can be hidden from the same page (panel.enabled).

Key · Default · Meaning enabled · true · Master switch; false removes the service, tools, snapshot, command, panel, and answerer (not editable from the settings page — a disabled plugin has no settings entry) panel.enabled · true · Show the web panel's floating button; saving false from the settings page hides the 🧠 entry immediately, no reload needed (the settings page itself stays reachable) dbPath · '' → $DSH_HOME/dsh-memento/memory.db · Absolute, or relative to $DSH_HOME (falls back to ~/.dsh on Windows) budgets.user.userGlobal · 2000 · Hard character budget for the user track's user-global layer budgets.user.workspace · 2000 · Hard character budget for the user track's workspace layer budgets.agent.userGlobal · 4000 · Hard character budget for the agent track's user-global layer budgets.agent.workspace · 4000 · Hard character budget for the agent track's workspace layer writePolicy · 'ask' · Default write policy: ask / auto / off (model-invisible) writePolicies · {} · Per-track/scope or per-source overrides (e.g. user/workspace, source:claude) language · 'en' · Model-visible and command output language: en / zh snapshotOrder · -50 · Snapshot section order (after harness identity, before persona) maxEntriesPerQuery · 20 · Default per-query result cap (hard-capped at 1000) commandListLimit · 50 · Entries rendered per /memory list / query commandAuditLimit · 10 · Audit rows rendered per /memory audit recall.historyLimitDefault · 8 · memory_recall sessions scanned by default recall.snippetCap · 5 · memory_recall snippets per session recall.snippetChars · 300 · memory_recall snippet characters recall.windowDays · 30 · memory_recall recency window in days retrieval.vector · false · Semantic recall switch: true enables memory_recall vector recall (fake hash embedding) when an embedding provider is available; otherwise degrades to substring panelEntriesLimit · 200 · Web panel entries page size panelAuditLimit · 20 · Web panel audit rows by default auditRetentionDays · 0 · Audit retention (0 = keep forever) proposals.enabled · true · Auto-capture a memory proposal after each successful compaction proposals.maxChars · 2000 · Proposal character cap proposals.maxPending · 8 · Pending proposal cap

Tools & surfaces

Surface · Kind · Notes memory · tool · add/replace/remove/consolidate/query with Save/Skip guidance; writes ride the approval gate memory_recall · tool · Bounded memory matches plus recent session-history matches /memory · command · list · query · add · remove · consolidate · proposals · budgets · audit · export · import · adapters web panel · client drawer · Read-only: browse entries, search, budget bars, audit tail; the floating entry button can be hidden (panel.enabled) settings section · DSH settings sidebar → dsh-memento · Edit every config field except enabled without touching files (namespace = the memento profile entry on the 0.1.7 line, the dsh-memento settings namespace before it); live vs reload-required timing is marked on the page

MCP server

dsh-memento ships a read-only stdio MCP server (dsh-memento-mcp) so external MCP clients (Claude, Codex, …) can search the memory store without a harness. It speaks JSON-RPC 2.0 over newline-delimited JSON (NDJSON) — one JSON object per line, no Content-Length framing.

Read-only. The database is opened with node:sqlite readOnly: true (no migrations, no WAL writes, no recall-count bump); a missing database returns empty results instead of crashing.

Tool · Purpose memory_search · {query, limit?} → ranked entries (case-insensitive substring via the retrieval Provider seam) memory_stats · {} → {total, namespaces} entry count + per-track/scope overview

Run it directly:

node bin/mcp-server.mjs
# or, after npm install: npx dsh-memento-mcp

The database path is $DSH_MEMENTO_DB_PATH (absolute, or relative to $DSH_HOME); it defaults to $DSH_HOME/dsh-memento/memory.db.

Claude Desktop (claude_desktop_config.json) example:

{
  "mcpServers": {
    "dsh-memento": {
      "command": "npx",
      "args": ["-y", "dsh-memento-mcp"],
      "env": {
        "DSH_MEMENTO_DB_PATH": "/home/you/.dsh/dsh-memento/memory.db"
      }
    }
  }
}

The server is read-only: no network, no writes, no approval gate — search and stats only.

How it's different

Plugin · What it is · dsh-memento's difference dsh-memory-evolve · memory warehouse / evolution loops · a typed service seam, approval gate, and session-log audit; no warehouse ambition dsh-mnemon · memory store helper · protocol + gate + audit, not another store dsh-kb-sieve · knowledge-base sieving · no retrieval engineering: small-corpus substring search, cross-session recall via session_search/sessionQuery dsh-tdai-memory · task-driven memory tooling · budgets are per track×layer and enforced in the service, not best-effort claude-bridge · Claude Code bridging · DSH-native; a future seed(source:'claude') path lets a bridge feed the same store dsh-external/Recall · external agent memory · local-first, zero-network, rides DSH's own approval seam Official MCP memory examples · DSH's stated "memory = external MCP" position · the native first-party complement: same goal, no external server; both coexist

The name is `dsh-memento` (published on npm and GitHub). Not dsh-recall (confusable with dsh-external/Recall), not the deleted legacy name dsh-memory.

dsh-memory-protocol v1

dsh-memento is the community rehearsal of the DSH memory protocol — a candidate shape for an official ctx.memory seam. The protocol normalizes this plugin's seam into a cross-plugin contract:

• Entry spec — two tracks × two layers × per-agent key, plus short tags (≤16 × ≤32 chars) and a per-entry version that increments on every replace.
• Write semantics — idempotent unique-substring conditional writes; approve-what-you-see payloads (replace / remove / consolidate carry the full text they change).
• Audit contract — every write reconstructable from approval/asked + approval/decided + the provider ledger.
• Budget model — BUDGET_EXCEEDED / AMBIGUOUS_MATCH semantics.
• Schema versioning — migration rules with loud version checks.
• Spec — docs/protocol-v1.md (中文: protocol-v1.zh.md); normative JSON Schema at docs/schemas/dsh-memory-protocol-v1.schema.json.

Adapter registry — ctx.memoryAdapters (register / list / adapt / export) lets third-party memory plugins speak the protocol by registering a pure data converter (reversible register(); import rides the approval-gated seed, export is read-only). Onboarding: docs/adapters-guide.md (中文: adapters-guide.zh.md).

Built-in adapter · External format · Notes mem0 · mem0 fact collections ({facts: [{memory, metadata?}]}) · metadata.category / metadata.tags become tags; raw messages arrays are rejected — adapters convert, never extract hermes-memory-md · Hermes memory.md (## section + bullets) · section names become tags; non-bullet prose fails loudly claude-code-memory-md · CLAUDE.md-style markdown (headings, bullets, paragraphs) · bullets and paragraphs become entries; section names become tags

Conformance suite — test/protocol-conformance/: a distributable case set any provider claiming compatibility runs (node test/protocol-conformance/run.mjs --provider ./your-factory.mjs); this repo's CI runs it against its own provider as the golden reference (npm run test:conformance).

• Upstream proposal — docs/upstream-proposal.md (中文: upstream-proposal.zh.md): why the official ctx.memory seam should adopt the protocol, the differences, and the migration path.

Permissions & data

• Permissions: declares harness:tool, filesystem:read, filesystem:write, and network:none / subprocess:none / shell:none / python:none / credentials:none in its workshop manifest. Write approval rides the official approval seam.
• Data: local SQLite database (0600), zero network, zero credentials.
• Session log: audit completeness comes from the approval pair (approval/asked + approval/decided) plus the plugin's own audit table; the session-log side of that gap is declared in /memory audit and disappears once the host registers memory/*.

Security boundaries

• Public services only. Consumes tools, systemPrompt, and the approval seam; no engine / agent-loop / apiproxy / official-UI changes.
• Zero network, zero credentials. Local database with POSIX file mode 0600.
• Fail loud. Corrupt DB, newer schema, or invalid config fails at load; full budgets and ambiguous substring matches fail with structured errors.
• One process, one store. Multiple sessions share the SQLite store; two processes sharing one $DSH_HOME write the same file (last-writer-wins under SQLite locking).

Known limitations

• Session events are declared, not yet emitted (rc.2). memory/added|updated|removed|recalled|snapshot are merge-declared, but rc.2 has no registration surface for out-of-repo event types; emission turns on once a harness build registers them.
• `ask` policy needs an answerer. With no UI/ACP answerer composed, writes fail closed.
• No FTS5 indexing. Substring search runs on case-insensitive instr (correct for CJK).

What we learned from the terminal memories

dsh-memento is not a port of Claude Code, Codex, or Hermes — but its design deliberately absorbed the parts each got right, and refused the parts that hurt:

Terminal memory · What it got right · What dsh-memento adopted Claude Code — CLAUDE.md · hierarchical plain-text memory files (user-level → project-level), human-readable and human-editable, merged automatically into every session · plain-text entries; user-global / workspace layers merged per session; a store you can browse, export, and audit — transparency as a feature Codex — AGENTS.md · per-directory scoped instructions auto-discovered and injected with zero model friction · the workspace layer keyed by the session cwd (Windows case-insensitive); the frozen snapshot injected automatically at session start Hermes — memory.md · proactive memory saves and the security lesson that a gate enforced only in the tool layer is bypassable by late tool injection · the memory tool with Save/Skip guidance + approval-gated auto-capture proposals; the gate lives inside ctx.memory's write methods, not in the tool layer

Sources: Claude Code memory · Codex AGENTS.md · Hermes memory · Hermes #48181.