dsh-memory-ga

Readme

# dsh-memory-ga

**Gated, file-based long-term memory for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)** — inspired by GenericAgent’s discipline: *No Execution, No Memory*.

> Your agent already has Skills.  
> What it usually lacks is a **small, trustworthy index of facts + rules**, a **session notepad**, and a **settlement ritual** that turns hard-won lessons into Skills / facts — without silently poisoning memory from every chat.

**Language:** English · [中文](./README.zh.md)

---

## Why this exists

Coding agents forget. Vector “auto-memory” products remember *too much* — drafts, wrong turns, guesses.

**dsh-memory-ga** takes the other path:

| Principle | What you get |
|-----------|----------------|
| **Verified only** | Long-term writes only after tools (or the user) confirmed reality |
| **Hard-injected L1** | A ≤~30-line index + RULES every turn — not a pointer you might never open |
| **Working notepad** | Session `key_info` re-injected while non-empty |
| **Gated settlement** | `start_long_term_update` opens a protocol; **it does not auto-edit your files** |
| **Skills stay Skills** | Reusable procedures → DSH Skills. Memory is **not** a second SOP warehouse |
| **Local & auditable** | Plain UTF-8 under `$DSH_HOME/memory` — diff, backup, hand-edit |

No embeddings required. No cloud bank. No silent retain.

---

## Architecture (deliberately small)

```
$DSH_HOME/memory/
  L0_memory_management.md   # constitution (how to remember)
  global_mem_insight.txt    # L1: NAV + RULES  → hard-injected
  global_mem.txt            # L2: verified facts → read on demand (≤9-line sections + pointers)
  l3/<topic>.md             # L3: long-form fact dossiers (L2 sections point here)
  .working/<session>.txt    # optional session notepad dump

DSH platform (not this folder)
  Skills / skill catalog    # procedures
  Sessions                  # full transcripts (query via DSH, not a memory “L4” tree)
```

**No notes-style junk drawer and no memory-tree L4.** `l3/` holds **fact dossiers only** — procedures belong to Skills (Skill = how-to, L3 = what-is).  
If a Skill is wrong, **fix the Skill** — don’t keep a shadow errata page in memory.

```
Verified + worth keeping?
  ├─ reusable workflow  → DSH Skill (+ optional L1 one-liner)
  ├─ env / config fact  → L2 (± L1 pointer)
  ├─ very long fact     → l3/<topic>.md dossier (+ L2 pointer)
  ├─ one global rule    → L1 RULES
  └─ this task only     → Working (or discard)
```

---

## Tools

| Tool | Role |
|------|------|
| `update_working_checkpoint` | Replace session notepad (`key_info`) |
| `start_long_term_update` | Return L0 + settlement protocol (**no automatic writes**) |
| `memory_status` | Paths, L1/L2 sizes, l3 dossier count, working empty?, nudge counters |

Optional **soft nudges** (default on): after enough steps, gently remind checkpoint / settlement. Never force tool calls. Never auto-write L1/L2.

---

## Install (DeepSeek Harness profile)

Compatible with DSH Cordis plugins (`dsh.bundle.patch`).

### A. From Git (recommended once published)

In your profile directory (example: `$DSH_HOME/profiles/web`):

```bash
pnpm add dsh-memory-ga@github:DiligenceLai/dsh-memory-ga
```

Ensure the profile loads the package (either list it under `dsh.profile.bundles` or rely on the package’s `cordis.patch.yml` insert — same pattern as other DSH community plugins).

### B. Local path (development)

```bash
pnpm add dsh-memory-ga@file:../path/to/dsh-memory-ga
```

> **Note:** some package managers **copy** `file:` deps. After editing the plugin source, reinstall/relink the profile dependency and restart DSH (or wait for profile HMR).

### C. Skill helper (optional)

Copy the bundled skill into the user skills root so the agent can load `memory-management`:

```text
skills/memory-management/SKILL.md  →  $DSH_HOME/skills/memory-management/SKILL.md
```

Restart or wait until the skill filesystem rescans.

---

## Quick verify

1. Restart DSH / reload the profile.  
2. In a session, run **`memory_status`** → should show `$DSH_HOME/memory`.  
3. **`update_working_checkpoint`** with a short note → next model step should include `### [WORKING MEMORY]`.  
4. **`start_long_term_update`** → protocol + full L0; disk unchanged until **you** edit.

First boot **creates missing** L0/L1/L2 from templates and **never overwrites** existing files.

---

## Configuration

Cordis config on plugin id `memory-ga` (optional):

```yaml
- id: memory-ga
  config:
    # root: null            # default: $DSH_HOME/memory
    bootstrap: true
    injectL1: true
    injectWorking: true
    l1MaxChars: 1200
    workingMaxChars: 1200
    persistWorkingFile: true
    nudge:
      enabled: true
      workingEvery: 12
      settleAfterSteps: 15
      maxWorkingNudges: 3
      maxSettleNudges: 2
```

**Hard dependency:** the plugin declares `inject: ["tools", "systemPrompt", "llm"]`. `@deepseek-ai/dsh-llm` (with `createUserMessage`) must be present in the host composition — working-memory and nudge injection rely on it. If it is missing, the plugin still loads but `memory_status` will warn that working/nudges are not injected, rather than silently failing.

`workingMaxChars` is the single cap for both storing and injecting the working notepad, so `memory_status.workingChars` always reflects what the model actually sees.

---

## What this is *not*

- Not a vector database / TEMPR / auto-git retain product  
- Not a replacement for DSH Skills  
- Not automatic Skill generation  
- Not a dump of full chat transcripts into `memory/`

If you want maximum automatic recall across tools, look at other stacks.  
If you want **controlled crystallization** and **git-friendly truth**, you’re in the right place.

---

## Privacy

This repository ships **generic templates only**.  
Your real L1/L2 live under **`$DSH_HOME/memory` on your machine** and are **never** part of this package.  
Do not commit personal memory files, tokens, or absolute home paths into forks.

---

## Development

```bash
git clone <this-repo>
cd dsh-memory-ga
pnpm install   # schemastery + peers for local smoke
```

Entry: `lib/index.js` (Cordis `name` / `inject` / `Config` / `apply`).

---

## Contributing

Issues and PRs welcome: install docs for more profiles, stronger nudge hooks, project-scoped memory overlays, session-search Skill examples.

---

## License

MIT — see [LICENSE](./LICENSE).

GenericAgent is a separate project; this plugin only **borrows the memory discipline**, not GA’s full runtime.