@dsh-external/dsh-local-memory

Readme

<div align="center">

# 🧠 dsh-local-memory

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

[![DSH Suite](https://img.shields.io/badge/DSH_Power_Suite-Local_Memory-blue?style=flat-square)](https://github.com/huangjua)
[![Storage](https://img.shields.io/badge/Storage-Local_Markdown-success?style=flat-square)](#)
[![License](https://img.shields.io/badge/License-BSD--3--Clause-orange?style=flat-square)](LICENSE)

[Features](#-key-features) • [Quick Start](#-quick-start) • [DSH Power Suite](#-dsh-power-suite) • [Tools](#-available-tools) • [Architecture](#-architecture) • [简体中文](README_zh.md)

</div>

---

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

```bash
# 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:

```mermaid
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](https://github.com/huangjua/dsh-local-memory)** | **Memory Layer** (Current) | Curates persistent long-term knowledge, developer profiles, and workspace conventions. |
| ⚡ **[dsh-context-economy](https://github.com/huangjua/dsh-context-economy)** | **Context Economy** | Slashes code reading tokens by 80–93%, leaving ample prompt budget for memory snapshots. |
| 🛡️ **[dsh-evidence](https://github.com/huangjua/dsh-evidence)** | **Audit & Receipts** | Creates SHA256 receipts for execution runs, grounding memory entries in verifiable evidence. |
| 🔍 **[dsh-session-index](https://github.com/huangjua/dsh-session-index)** | **Session Search** | Indexes raw `.jsonl.zstd` logs with CJK support. Memory curation belongs here; log searching belongs there. |

---

## 📖 Deep Dive & Reference

<details>
<summary><b>🛠️ Available Tools & Commands (8 Tools + 1 Command)</b></summary>

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

</details>

<details>
<summary><b>📁 Architecture & Storage Layout</b></summary>

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

</details>

<details>
<summary><b>⚖️ Design Trade-offs & Boundaries</b></summary>

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

</details>

<details>
<summary><b>🧪 Building & Testing</b></summary>

```bash
# Install dependencies
pnpm install --frozen-lockfile

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

# Typecheck & Run test suite
npm run typecheck
npm test
```

</details>

<details>
<summary><b>🙏 Credits & References</b></summary>

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

</details>

---

<div align="center">
<sub>Part of the <a href="https://github.com/huangjua">DSH Agent Power Suite</a>. Licensed under BSD-3-Clause.</sub>
</div>