# 🧠 dsh-local-memory
**Persistent cross-session local memory for DSH agents**
*100% Local • Plain Markdown Truth • Self-Healing SQLite Mirror • Prefix-Cache Friendly*
[](https://github.com/huangjua)
[](https://raw.githubusercontent.com/huangjua/dsh-local-memory/main/#)
[](https://raw.githubusercontent.com/huangjua/dsh-local-memory/main/LICENSE)
[Features](#-key-features) • [Quick Start](#-quick-start) • [DSH Power Suite](#-dsh-power-suite) • [Tools](#-available-tools) • [Architecture](#-architecture) • [简体中文](https://github.com/huangjua/dsh-local-memory/blob/main/README_zh.md)
💡 Why dsh-local-memory?
DSH agents are natively stateless. Every new conversation starts from zero, forcing you to repeatedly explain project rules, environment setups, and coding preferences.
dsh-local-memory gives your agent long-term memory that you actually own:
- 📝 Markdown is the Single Source of Truth: All memories are stored in plain
.mdfiles under~/.dsh/memory/. You can view, edit, or version-control them with Git. - ⚡ Zero Cache Misses: Employs per-session frozen snapshots (
WeakMap<Session, ...>) to maintain byte-for-byte prefix cache stability, saving tokens and speeding up responses. - 🔒 100% Local & Fail-Closed: No cloud leaks. Workspace boundaries strictly validated against official workspace registries.
- 🛡️ Staged Write Approvals: Global profile edits require explicit user confirmation (
memory_pending approve) to prevent hallucinated changes.
🚀 Quick Start
Installation
# In your DSH plugin environment
dev_inject_plugin @dsh-external/dsh-local-memoryTypical Usage Flow
- Ask agent to remember: "Remember that our project uses pnpm and strict TypeScript."
- Review staged memory: Run
/local-memoryor approve staged entries viamemory_pending. - Seamless recall: In any new session, the agent automatically receives the frozen memory context without any extra prompts.
🧩 DSH Power Suite
This plugin is part of the DSH Agent Power Suite — 4 modular, zero-hard-dependency plugins forming a complete closed-loop developer workflow:
flowchart LR
M["🧠 dsh-local-memory<br>(1. Remember rules & prefs)"] --> E["⚡ dsh-context-economy<br>(2. Save 80%+ tokens reading code)"]
E --> A["🛡️ dsh-evidence<br>(3. Tamper-proof audit receipts)"]
A --> S["🔍 dsh-session-index<br>(4. CJK search & bookmarks)"]
S --> M
style M fill:#e8f4fd,stroke:#2b7de9,stroke-width:2px
style E fill:#eef9f2,stroke:#1e8e3e,stroke-width:2px
style A fill:#fef7e0,stroke:#f29900,stroke-width:2px
style S fill:#f3e8fd,stroke:#8430ce,stroke-width:2px| Plugin | Role in Suite | Synergy with Local Memory |
|---|---|---|
| 🧠 dsh-local-memory | Memory Layer (Current) | Curates persistent long-term knowledge, developer profiles, and workspace conventions. |
| ⚡ dsh-context-economy | Context Economy | Slashes code reading tokens by 80–93%, leaving ample prompt budget for memory snapshots. |
| 🛡️ dsh-evidence | Audit & Receipts | Creates SHA256 receipts for execution runs, grounding memory entries in verifiable evidence. |
| 🔍 dsh-session-index | Session Search | Indexes raw .jsonl.zstd logs with CJK support. Memory curation belongs here; log searching belongs there. |
📖 Deep Dive & Reference
🛠️ Available Tools & Commands (8 Tools + 1 Command)
### Tools | Tool | Description | Scope / Action | |---|---|---| | `memory_write` | Add a new memory entry | User/Profile ➡️ Staged; Workspace ➡️ Direct | | `memory_update` | Revise an entry via `memoryId` or `oldText` | Previous active marked `superseded` | | `memory_forget` | Remove an entry from active memory | Replaced with minimal tombstone | | `memory_pending` | Manage staged approvals | `list`, `approve`, `reject` | | `memory_append_daily`| Append timestamped block to daily notes | Append-only workspace scratchpad | | `memory_search` | Search memories with FTS5 trigram | Auto pre-syncs modified Markdown | | `memory_status` | Detailed file counts, active entries, DB size | Read-only diagnostics | | `memory_distill` | Collect candidate daily notes for distillation | Read-only + state metadata | ### User Commands - `/local-memory feedback📁 Architecture & Storage Layout
```text ~/.dsh/memory/ ├── user/ # User-level profile & global memories (MEMORY.md / USER.md) ├── workspaces/⚖️ Design Trade-offs & Boundaries
| Advantage | Trade-off / Boundary | |---|---| | SSOT/Replica separation ensures zero data loss | Schema v12 migration chain requires strict maintenance | | Dual channel: frozen snapshots + real-time tool search | Local-machine bound (no cloud sync) | | Strict workspace fail-closed isolation | Index contains plain text (do not use on untrusted shared machines) | | 566 test cases with comprehensive coverage | `forget` removes active surfaces, does not do physical disk shredding |🧪 Building & Testing
```bash # Install dependencies pnpm install --frozen-lockfile # Build TypeScript to lib/ bash scripts/build.sh # Typecheck & Run test suite npm run typecheck npm test ```🙏 Credits & References
- **Hermes Agent** (Nous Research, MIT): `entries.ts`, `threat.ts`, and `approval.ts` adapted from `memory_tool`, `threat_patterns`, and `write_approval`. - **Official dsh-plan-mode** (MIT): `WeakMap
Part of the DSH Agent Power Suite. Licensed under BSD-3-Clause.