dsh-local-memory

💡 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

📖 Deep Dive & Reference

~/.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

# Install dependencies
pnpm install --frozen-lockfile

# Build TypeScript to lib/
bash scripts/build.sh

# Typecheck & Run test suite
npm run typecheck
npm test