@guntur-d/dsh-memory

Readme

# dsh-memory

Persistent cross-session memory plugin for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness). Facts the model saves are stored durably **per workspace** (the owning session's `cwd`) on the harness storage-domain seam, and injected as a bounded prompt section into later sessions in the same workspace — so something important established in one session carries over to the next.

- `ctx.memory` service: `save` / `list` / `search` / `forget`
- Model tools: `memory_write`, `memory_list`, `memory_search`, `memory_forget`
- Prompt section: `app:memory` (order 50, default 8 lines) in every session of the workspace

## Requirements

The harness profile must mount the storage seam with a backend:

- `@deepseek-ai/dsh-storage` (the hub)
- `@deepseek-ai/dsh-storage-json` (default, human-readable JSON files) or `@deepseek-ai/dsh-storage-sqlite`
- `@deepseek-ai/dsh-storage-domain` (the domain facility this plugin opens the `memory` domain on)

The shipped `web` profile already mounts all three with the `json` backend — no extra setup needed there.

## Install

```sh
# from this repo (sources build on install via prepare)
dsh plugin --profile web add github:guntur-d/dsh-memory

# or from npm once published
dsh plugin --profile web add @guntur-d/dsh-memory
```

The `dsh.bundle.patch` manifest field makes the plugin a **bundle layer**: the included `cordis.patch.yml` row activates the plugin automatically in the profile. GitHub-topic discovery: [`dsh-plugin`](https://github.com/topics/dsh-plugin).

## Usage

The model calls `memory_write` when something durable is established (a port, a preference, a non-obvious project fact). You can prompt it explicitly:

```
Please remember: the staging server listens on port 3080 and the deploy script is deploy.sh
```

A later session in the same workspace starts with an `app:memory` section listing the recent memories, and can `memory_list` / `memory_search` / `memory_forget` (by id) on demand.

## Config

```ts
interface Config {
  maxEntriesPerWorkspace: number // default 500; the oldest are evicted past it
  maxTextChars: number           // default 2000; longer saves are refused
  maxContextEntries: number      // default 8; memories rendered into the prompt section
  maxListEntries: number         // default 50; memories one list/search call returns
}
```

The storage backend route is decided by the deployment's `dsh-storage-domain` config (`routes` for the `memory` domain, else its default `backend`).

## Semantics

- Entries are scoped by the owning session's `cwd`; sessions without a `cwd` share one anonymous workspace.
- A monotonic `seq` (minted on the domain's atomic write chain) keeps ordering and eviction deterministic even when wall-clock timestamps tie.
- Saves and forgets await durability on the backend; reads are synchronous from the domain's in-memory state.
- The model decides what is worth saving — no automatic summarization.

## Develop

```sh
pnpm run check       # typecheck against a deepseek-harness checkout (tsconfig.check.json)
```

Notes:
- The npm-published `@deepseek-ai/*` dependency chain is currently incomplete (a peer package `@deepseek-ai/dsh-type-meta` is not published), so a from-npm `pnpm install` of this plugin fails until upstream completes the publish chain. The `tsconfig.check.json` typechecks this source against a local `deepseek-harness` checkout instead (edit the absolute path in its `paths` if your checkout lives elsewhere).
- Until the npm chain is fixed, install the plugin from a checkout: `dsh plugin --profile web add .` from this repo (the profile resolves `@deepseek-ai/*` through the harness installation).