dsh-memory-panel

Readme

# dsh-memory-panel

Long-term memory for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (`dsh`): durable, cross-session memory tools plus a sidebar panel that shows what the agent remembers about you.

[English](README.md) | [中文](README.zh.md)

## What it does

- **`memory_save`** — store a memory (creates or updates by key)
- **`memory_recall`** — search memories by keyword or category
- **`memory_list`** — list all memories, optionally filtered by category
- **`memory_delete`** — delete one memory by its exact key
- **`memory_clear`** — delete ALL memories (requires `confirm: true`)
- **Sidebar memory panel** — a "Memory" button in the web sidebar opens a panel visualizing the memory store (bilingual, follows the UI language)

Memories live in `~/.dsh/memory.json` — plain JSON on your machine, nothing leaves it.

## Features

- **Atomic writes**: write-to-temp + rename, readers never see a torn file
- **Write serialization**: concurrent `memory_save` calls queue instead of clobbering each other
- **Corruption recovery**: a broken `memory.json` is backed up to `memory.json.corrupt-<ts>` before continuing fresh — no silent data loss
- **Growth control**: content capped at 4000 chars, store capped at 500 entries (oldest evicted), recall results capped at 30
- **Optional filter**: `memory_list` works with or without `category_filter`
- **Delete & clear**: `memory_delete` removes one memory; `memory_clear` empties the whole store after an explicit `confirm: true`
- **Bilingual UI**: the panel follows the UI language (zh / en) via the dsh locale service
- **Tunnel-aware UI**: the panel warns when accessed through a tunnel where the browser-trust fence blocks `/api/*`

## Install

```sh
# web profile (interactive GUI)
dsh plugin --profile web add dsh-memory-panel

# headless profile (one-shot runs) — same bundle, separate install
dsh plugin --profile headless add dsh-memory-panel
```

Install from GitHub directly (no npm needed):

```sh
dsh plugin --profile web add github:x2it/dsh-memory-panel
```

Restart `dsh web` after installing, then open the sidebar "记忆" button.

## Verify

```sh
dsh --profile web --dump-config | grep memory-panel
```

The agent should now list `memory_save` / `memory_recall` / `memory_list` among its tools.

## How it works

```
agent tools (memory_save/recall/list)
        │  ctx.tools.register
        ▼
  host plugin (lib/index.js)
        │  GET /api/memory  (ctx.webServer)
        ▼
  client panel (lib/client.js, sidebar.footer.action slot)
```

One plugin row (`memory-panel`) carries both halves: the host loader imports `main`, the web client loads `./client`.

## Development

```sh
npm install
npm run typecheck   # tsc --noEmit
npm run build       # esbuild → lib/index.js + lib/client.js
npm pack            # tarball
```

Install the local tarball to test before publishing:

```sh
npm pack
dsh plugin --profile web add ./dsh-memory-panel-0.1.0.tgz
```

## Layout

```
src/index.ts          # host half: memory tools + /api/memory endpoint
src/client/index.tsx  # client half: sidebar memory panel
lib/                  # built artifacts (generated by build.mjs)
cordis.patch.yml      # bundle patch (dsh.bundle.patch)
```

## Security

The `/api/memory` endpoint has no authentication — bind dsh web to localhost or a trusted network. The plugin stores memory content in plaintext at `~/.dsh/memory.json`; do not save secrets you would not write to a local file.

## License

MIT