384961890-ui / pawin-brain-deepseek-harness

Pawin Brain · DeepSeek Harness

A brain-inspired agent runtime.
Remember · self-correct · learn — v0.1 starts with memory, the foundation of both.

Quick start · How it works · Security · Configuration · Development

---

[!NOTE] This is an independent community plugin by the Pawin project — it is not an official DeepSeek product.

The brain idea

Pawin Brain is not a memory plugin — it is a brain-inspired runtime for agents, built around one loop:

remember ──► self-correct ──► learn
   ▲                             │
   └─────────────────────────────┘

• Remember — an agent that cannot recall its past cannot learn from it.
• Self-correct — surface contradictions, repeated failures, and missing evidence instead of glossing over them.
• Learn — a lesson only counts when a later, different session changes its behavior, not when it merely writes a note about itself.

v0.1 ships the remember stage — the hippocampus. It is deliberately the foundation: every later stage reads what this one wrote down.

What v0.1 ships

The first, fully-tested slice of the runtime, for DeepSeek Harness:

1. Per-turn injection — recent diary entries enter the model's context at the start of every turn.
2. brain_note — append a fact worth remembering to today's diary.
3. brain_recall — multi-word AND search over past diary entries.

Memory is a directory of plain Markdown files. No database, no network, no external service. Delete the directory and all memory is gone.

Roadmap

The later stages of the loop — self-correct (conflict monitoring, repeated-failure detection) and learn (behavior-differential proof) — are under active development and will ship as later versions. Memory is released first because every other stage depends on it.

<memoryRoot>/
└── diary/
    ├── 2026-08-13.md   # append-only, one [HH:MM] entry per line
    └── 2026-08-12.md

Quick start

Run from a DeepSeek Harness checkout:

pnpm dsh web --patch examples/demo.cordis.yml

Open http://127.0.0.1:3080 and say:

Note down that my favorite drink is oolong tea.

Then, in a new session (no need to restart the server):

What is my favorite drink? Check memory with brain_recall.

The agent recalls it from the diary on disk.

How it works

flowchart LR
    U[User turn] --> P[agent/pre-step]
    P -->|inject today's diary| M[Model request]
    M -->|calls| N[brain_note]
    M -->|calls| R[brain_recall]
    N --> D[(diary/YYYY-MM-DD.md)]
    R --> D
    D -->|next turn| P

• Injection hooks agent/pre-step (waterfall) and appends one source-attributed message per turn — never more than once a turn, and never when the diary is empty.
• Tools go through the normal ctx.tools registry: runtime argument validation, sandbox policy, approval, and teardown all behave as with any first-party tool.
• Storage is append-only with O_APPEND; concurrent appends do not clobber each other.

Security

dsh-brain treats the diary as untrusted input and the filesystem as hostile:

Boundary	Behavior
Dates	Strict YYYY-MM-DD calendar-roundtrip validation; 2026-02-30 is rejected
Path traversal	Rejected at the date-parameter level; a second join check stays as defense
Symbolic links	Rejected at three layers: memory root, diary/ dir, and each diary file
Content	NUL bytes, overlong lines, and over-budget appends are rejected loudly
Reads	Byte-budgeted with newest-tail truncation; 64 MB hard cap per file
Writes	O_APPEND atomic appends; concurrent writes never interleave
Config	Invalid configuration fails at plugin load — never silently

Configuration

Field	Default	Meaning
memoryRoot	~/.dsh-brain-memory	Memory root (absolute or ~-prefixed)
injectDiaryDays	2	Recent diary days injected per turn (incl. today), 1–7
injectMaxBytes	8192	Total injection byte budget
noteMaxBytes	8192	brain_note per-call byte budget
recallMaxResults	20	brain_recall max returned hits, 1–500
recallSnippetChars	240	Per-hit display characters, 1–4000
recallScanDays	30	brain_recall scan window in calendar days, 1–365

Example mount entry (examples/demo.cordis.yml):

- insert:
    - id: dsh-brain
      name: '/absolute/path/to/dsh-brain/src/index.ts'
      config:
        memoryRoot: '~/.dsh-brain-memory'

Development

This plugin is developed as a standalone directory inside a DeepSeek Harness checkout (its @deepseek-ai/* dependencies resolve through the harness workspace).

# unit tests + real-composition test; per-file 100% coverage gate
./node_modules/.bin/vitest run --config vitest.config.ts --coverage

# typecheck (paths map every @deepseek-ai/* package to its built lib/types)
./node_modules/.bin/tsc --noEmit -p tsconfig.json

# lint (harness .oxlintrc.json)
./node_modules/.bin/oxlint -c .oxlintrc.json src tests

Current state: 84 tests passing, 100% coverage across statements / branches / functions / lines, typecheck and lint clean.

The real-composition test boots a headless assembly through the harness's own Loader; a deterministic mock LLM really calls brain_note and brain_recall, and the test asserts that the second turn's injection sees the first turn's write.

License

MIT © Pawin

Not affiliated with or endorsed by DeepSeek.