dsh-cipher

Readme

# dsh-cipher

A DeepSeek Harness plugin package that brings cipher's core design — persistent thinking, the three platforms (execution / insight / memory), four local memory types (attention, experience, preference, cognitive), and the UNNI/LOOP session modes — to DSH as a native bundle (no Rust process, no cipher binary required).

After installing and configuring a model in DSH, **UNNI and LOOP become selectable in DSH's native agent-preset picker** (next to Standard / PTC / Minimal). Conversations composed from one of these presets get the full cipher pipeline: every turn is sedimented into four memory types, recalled cross-session, and LOOP sessions self-continue after each sediment round.

## Features

- **UNNI / LOOP as native agent presets**: on activation the plugin materializes two presets (copies of your deployment's `standard` preset + the cipher rows) into the user preset root — they show up in the native picker immediately, no restart
- Four-type memory (attention / experience / preference / cognitive) sedimented after every turn via 4 memory agents (one LLM call each, parallel, error-isolated)
- Cross-session recall with deterministic retrieval (per-type quota + 14-day time decay + term/keyword matching) injected into the system prompt (`systemPrompt.context`, re-recorded only when the snapshot changes)
- Insight review (recorded, three-question self-check per turn) whose output feeds memory only — never shown raw to the user
- Per-session mode override: a `Cipher·UNNI / Cipher·LOOP` toggle in the session header (cipher-preset sessions only); LOOP auto-continuation uses interval + run-count guards via `Agent.followup`, independent of DSH goal APIs
- Two model tools: `cipher_memory_search`, `cipher_memory_ingest`
- Settings page (SOUL editor, quotas, LOOP guards, fallback defaults) and a sidebar AgentPool panel showing live subagent status
- Editable SOUL injected as a static session-start section (provider caching friendly)

## Install

```sh
dsh plugin --profile <name> add dsh-cipher
```

What you get after install:

- **UNNI · 交互协同 / LOOP · 记忆驱动** in the native agent-preset picker (conversation composer seat and Settings → General). The two presets are materialized into the user preset root (`~/.dsh/.agent-presets/`) by copying your deployment's `standard` preset and appending the cipher rows. Re-synced automatically on plugin upgrade; removed on uninstall. A user-authored preset with the same id is never touched.
- A **Cipher** settings section (Settings → Cipher): SOUL editor, LOOP interval/run limits, per-type quotas, sediment/insight toggles
- A right-side collapsible **Cipher 池** (AgentPool) panel (subagent mode/activity/label, 5s refresh): expanded it docks as a full-height right panel, collapsed it folds into a slim right-edge rail that doubles as the entry point — styled after the native session/workspace panels
- A **Cipher·UNNI / Cipher·LOOP** toggle in the session header — shown only in cipher-preset sessions
- Two tools: `cipher_memory_search`, `cipher_memory_ingest` (only in cipher-preset sessions)

## Quick start

1. Configure the model in Settings → Models (the plugin reuses DSH's default model route).
2. Start a conversation and pick **UNNI** or **LOOP** in the preset picker, then type a message. After the turn, memories are sedimented automatically.
3. Ask "what do you remember about me?" in a following turn — recalled memories are injected.
4. In a LOOP session, the agent continues by itself after each sediment round (guards: interval + run cap), or switch a session with the header toggle.

## Requirements

- Node.js >= 22.19
- DSH with the agent-presets roster and a writable user preset root (both defaults): the presets are authored via `agentPresets.copy('standard', ...)` — the deployment's `standard` preset (or the default preset) is the composition source. Without it the plugin still runs (settings/pool), but the UNNI/LOOP presets cannot be materialized and no cipher rows activate.
- Model configured in DSH; memory agents and insight review make one LLM call per agent per turn (in UNNI/LOOP sessions — cost is by design, see mode semantics)
- `storageDomain` is optional: when the composition mounts storage, memory persists to the deployment `storages` directory (`cipher_memory` domain). Without it, the plugin degrades to in-process memory (warned once, not durable across restarts).

## How it works

The bundle rows split into two planes (v0.1.2, "Design A" — cipher capabilities exist only inside the UNNI/LOOP presets):

| Plane | Row | Responsibility |
| --- | --- | --- |
| host (bundle patch) | `dsh-cipher/core` | Private service `ctx.cipher`: four-type memory store, deterministic retrieval, quotas, session mode, settings namespaces |
| host | `dsh-cipher` | Dual-face panel row: host REST routes (config/settings/mode/subagents) + client settings page / pool panel / header toggle |
| host | `dsh-cipher/presets` | Materializes the UNNI/LOOP presets (copy `standard` → append cipher rows → metadata; idempotent, version-marked, self-healing) |
| preset (UNNI/LOOP) | `dsh-cipher/memory` | Sediment: `session/event` turn/end → evidence → 4 memory agents → store (deduplicated, per-session watermark) |
| preset | `dsh-cipher/insight` | Evidence review (three-question self-check) → output sedimented as `[INSIGHT]` experience |
| preset | `dsh-cipher/prompt` | Injection: SOUL+mode `section` (order 60, static snapshot) + four-type memory `context` (re-recorded only on snapshot change) |
| preset | `dsh-cipher/mode` | Mode pinning (`presetMode` row config, written as the session default at creation) + LOOP followup scheduling after sediment |
| preset | `dsh-cipher/tools` | `cipher_memory_search` / `cipher_memory_ingest` |

Preset rows are mounted once per preset (standing mount) and joined per session by scope, exactly like other DSH preset rows. Sessions composed from Standard/PTC/Minimal have no cipher rows at all.

Storage note: the memory domain is optional at runtime — storage faults (for example headless one-shot teardown windows) degrade to in-memory storage for the process instead of failing the turn.

## Mode semantics (v0.1.2)

- **UNNI** (interactive): user and agent cooperate; execution/insight outcomes become sedimented evidence, and replies always come from the agent itself (platform outputs never surface raw — information isolation).
- **LOOP** (memory-driven): after each turn's sediment completes, the session re-arms itself with the freshest attention/experience memory as direction (guards: minimum interval, per-session run cap). Converged or stopped by the user, it wraps up quietly.
- The preset pins the session's default mode (row config `presetMode`); the header toggle overrides it for that session (stored in the `modes` table), and the settings default is the last fallback.

## Data & privacy

- Memories live in the deployment storages directory (`cipher_memory` domain; per process when no storage is mounted).
- All memory is local. Sediment/insight/loop calls go through DSH's default model route.

## Model experience (KV cache effect)

Per DSH package convention:

- **SOUL + mode section (order 60)**: stable repeated prefix — text unchanged within a session, provider prompt cache remains reusable; editing SOUL in settings replaces existing request tokens on the next assembly.
- **Memory `context` (`cipher-memory`)**: append-only growth — re-recorded only when the full snapshot changes (new sediment or compaction removal); zero re-record otherwise.
- The memory injection block is evaluated per assembly but yields stable text when nothing changed.
- `cipher_memory_search/ingest` are independent requests; they do not affect session request caching.

## Development

```sh
pnpm install
pnpm build          # tsc (host lib/) + tsdown (client/client.js, __ModuleLoader__ format)
pnpm test           # vitest (retrieval, evidence boundaries, preset materialization)
pnpm preflight      # publish artifact checks
```

- Service packages (`@deepseek-ai/dsh-*`) are declared as peers and resolved against the DSH install; only `zod` is a direct dependency.

## Security

Installing a plugin runs third-party code with your own permissions — review the source before installing. This package runs no post-install scripts beyond building its own artifacts (`prepare`).

## License

MIT