dsh-governed-memory

Readme

# DSH Governed Memory

[中文](README.zh-CN.md)

`dsh-governed-memory` is an opt-in, standalone [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) bundle. It contributes one Cordis host plugin through its own `cordis.patch.yml`; it is not a fork of Harness and ships no Harness source.

## Install

Install the repository into a DSH profile, then restart that profile:

```sh
dsh plugin --profile web add https://github.com/haoyuan-sjtu/Deepseek-Harness-Lifelong-Agent.git
```

The installed package declares `dsh.bundle.patch`, so DSH adds its patch layer to the selected profile automatically. The same package can be installed in the headless profile by replacing `web` with `headless`.

## Behavior

The bundle mounts one `agent/pre-step` waterfall listener. It calls `next()` first, then reads the registry and appends one plugin-sourced user message only when the registry selects one or more records. The DSH agent loop records the admitted message as an ordinary `user/message` event, including its source and rendered snapshot.

Records are stored in an atomic JSON registry. The plugin never registers a model-callable capture or promotion tool:

- `capture()` always writes `quarantine`.
- `promote()` requires a trusted host caller, explicit approval, and verified A/B evidence.
- retrieval admits only promoted records that are in scope, allowed by privacy, not expired or review-due, non-conflicting, relevant, and within the token budget.
- `revoke()` makes later retrieval deny the record.

The technical preview supports only `local` and `project` scopes. It rejects `user` and `team` configuration until the host provides identity, membership, and shared-storage authorization.

## Configuration

The package's patch inserts this row. A profile or home `cordis.patch.yml` can replace the complete `config` object.

```yaml
- id: governed-memory
  name: dsh-governed-memory
  config:
    registryPath: !!js process.env.DSH_GOVERNED_MEMORY_REGISTRY
    scope: project
    allowedPrivacy: [public, internal]
    tokenBudget: 512
    queryTags: []
```

`registryPath` defaults to `$DSH_HOME/governed-memory.json` when the environment variable is absent. The registry is written with mode `0600` and an atomic rename. Put it on local storage; this release does not provide backup deletion, multi-process locking, or shared-team access semantics.

## Trusted host operations

At boot the plugin exposes its registry as `ctx.governedMemory` for another trusted host plugin in the same DSH process. It has no browser UI, HTTP endpoint, CLI command, or model tool; promotion therefore cannot be forged by a model request.

```js
await ctx.governedMemory.capture(candidate, 'admin-ui')
await ctx.governedMemory.promote(candidate.id, true, 'admin-ui')
await ctx.governedMemory.revoke(candidate.id, 'admin-ui')
```

Every candidate needs `id`, `text`, `scope`, `privacy`, `canonicalKey`, `tags`, `evidence`, ISO-8601 `createdAt` / `reviewBy` / `expiresAt`, `confidence` between zero and one, and a positive `maxTokens`. Evidence entries require `uri`, `locator`, `level` (`A`, `B`, or `C`), and `verified`.

## Verify a checkout

```sh
npm run check
npm pack --dry-run
```

The tests exercise waterfall delegation, persistent capture/promotion, model-message injection, disposal, and default denial for unsafe records.

## Technical-preview limits

This is a local, single-process plugin. It has not completed a clean-profile installation test on every DSH release, a representative C0–C3 evaluation suite, backup deletion verification, or shared authorization. Do not store credentials, raw private transcripts, or material that cannot safely enter a model prompt.

## License

MIT. See [LICENSE](LICENSE).