💡 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
.md files 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-memory
Typical Usage Flow
- Ask agent to remember: "Remember that our project uses pnpm and strict TypeScript."
- Review staged memory: Run
/local-memory or approve staged entries via memory_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 <receipt-id> bundle <helpful|harmful>: Submit feedback on memory delivery receipts.
📁 Architecture & Storage Layout
~/.dsh/memory/
├── user/ # User-level profile & global memories (MEMORY.md / USER.md)
├── workspaces/<WorkspaceId>/ # Workspace-scoped memories (MEMORY.md)
├── daily/<WorkspaceId>/ # Daily scratch notes (YYYY-MM-DD.md)
├── summaries/ # Distilled summaries
├── pending/memory/ # Staged write approvals
├── index/memory.sqlite # Derived FTS5 SQLite index mirror (Schema v12)
└── meta.json # Metadata & version tracking
Key Architectural Invariants:
- Markdown is the Single Source of Truth: All text and metadata reside in
.md files.
- SQLite is a Disposable Replica: If corrupted, SQLite automatically recovers from Markdown via
buildMemoryIndex.
- Pre-Search Incremental Sync:
memory_search syncs changed files on the fly by content_hash.
⚖️ 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
# 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<Session, ...> freezing + systemPrompt.section dynamic provider pattern.
- Jesse-njx/dsh-memory (MIT): Managed entry inline HTML header metadata format.
- ben7am1n/dsh-memory (MIT): Live Context test harness architecture.
