@huangjua

dsh-local-memory

Name: dsh-local-memory
Availability: InStock
Author: huangjua

🧠 Persistent cross-session local memory for DSH agents (Markdown SSOT + self-healing SQLite mirror)

Stars: 0
Language: TypeScript
Created: Sep 1, 2026
Updated: Sep 1, 2026

Memory

GitHub repo

Introduction

🧠 dsh-local-memory

Persistent cross-session local memory for DSH agents
100% Local • Plain Markdown Truth • Self-Healing SQLite Mirror • Prefix-Cache Friendly

Features • Quick Start • DSH Power Suite • Tools • Architecture • 简体中文

💡 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.

_{Part of the DSH Agent Power Suite. Licensed under BSD-3-Clause.}