---

💡 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

1. Ask agent to remember: "Remember that our project uses pnpm and strict TypeScript."
2. Review staged memory: Run /local-memory or approve staged entries via memory_pending.
3. 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.

---