chenhw7/dsh-memory

Cairn

Cairn is long-term memory for the DeepSeek Harness, packaged as the @chenhw7/dsh-memory profile bundle — facts, preferences, corrections, and lessons survive across sessions and restarts.

This is a self-contained single package (not a multi-package workspace). It depends on dsh core services as peer dependencies (provided by the dsh installation you already have) and ships its own cordis.patch.yml so dsh plugin add activates it as one profile layer.

English | 简体中文

Interactive Deep-Dive

A single-file, zero-dependency illustrated walkthrough of the whole pipeline — signal capture, storage, retrieval, injection, and decay. The figures are not static: the extraction loop, the write-path security gates, the BM25 kernel ported from src/store/bm25.ts, and a decay simulator all run live in your browser. It is served from this repo via GitHub Pages:

→ Open the live page: memory-architecture.html · 简体中文版

Table of Contents

• Interactive Deep-Dive
• Features
• Install
• Update
• Uninstall
• Verify
• Configuration
• Architecture
• Known Limitations
• License

Features

Your dsh agent normally forgets everything when you close a session. This bundle fixes that:

• Persistent memory — facts, preferences, and conventions stored in a durable KV backend with audit logging.
• Three-layer scoping — global (cross-project), project (per-repo, auto-detected), and user (cross-project profile).
• Nine memory tools + the identity tool — memory_search, memory_add, memory_replace, memory_remove, memory_list, memory_get, memory_pin, memory_unpin, memory_forget, plus identity_update (below).
• Identity layer (opt-in) — the agent's two self-documents, SOUL.md (its character) and USER.md (its understanding of you), grown by the agent in conversation through identity_update and injected into every session (soul @80 / user-profile @81, coexisting with — and yielding to — the deployment persona; explicit conversation instructions always win). Seeded once from built-in Chinese copy, versioned with full history, never decayed. You hold no editor — only governance: a read-only Identity settings section with version history, a two-step revert valve (default on, separate from the remote write switch), and markdown export. Extraction never persists identity restatements (prompt rule + mechanical prefilter), and an eval slice + --identity axis pin the injection surface (see TECH_DESIGN §7.10).
• BM25 relevance search — dependency-free Okapi BM25 over CJK-aware tokenization (Latin word tokens; CJK unigrams + bigrams), pinned entries surfaced ahead of equal-relevance matches. Retrieval quality is not vibes: a fixed golden set (35 entries × 35 query sets, English + Chinese) is evaluated in CI — success@5 = 100%, MRR = 0.902 — with injection-cost numbers per prompt mode (see TECH_DESIGN §7.9).
• Automatic learning — a projection accumulator watches the conversation for explicit remember-intent, corrections, and verified failure streaks (repeated same-signature tool failures resolved by a success), then runs LLM extraction when enough candidates accumulate. Admission rules exclude anything the repository already records (code structure, git history, fixed-bug narratives), and model-handwritten date prefixes are stripped so timestamps always come from the program.
• Project notes prompt section — coding conventions and a pitfall log render into every session's system prompt (project-notes section). Nothing is written into your repository: memory lives entirely in the host-side store, is managed in the Memory settings UI, and upgrades automatically clean up notes files left by ≤0.5.x installs.
• Digest-first injection (default) — the system prompt carries only frozen guidance; the data rides step-tail messages instead: a one-time <memory-digest> inventory of the store (category counts + anchor topic words, re-appended once after compaction) on the session's first step, and per-step <recalled-memory> fences when the step's text matches stored entries. The prompt prefix stays byte-stable all session, and nothing resident has to be evicted on re-freeze.
• Dedup pipeline — two-stage deduplication (stop-word-filtered Jaccard prefilter + optional LLM judge with bounded merges) prevents near-duplicate accumulation; a low-frequency curator pass re-summarizes oversized entries.
• Two-tier memory lifecycle — pin important memories; overdue project-scoped entries are removed while overdue global/user entries are soft-decayed (hidden from standing injections, still searchable, un-stamped on recall); entries can also be manually archived from the UI; every write is audited.
• Step-level auto recall (on by default) — on each agent step, a BM25 search keyed on the step's user text appends a fenced <recalled-memory> message without touching the system prompt, keeping the KV-cache prefix stable. Fence hits refresh an entry's recency clock but never its access count, so query-word luck cannot inflate the eviction signal.
• Compaction-aware flush — when compaction shadows old context, the raw events are scanned for anything worth remembering.
• Security scanning, write and load time — API keys, tokens, prompt-injection patterns, and exfiltration attempts are blocked from being saved; anything that slips through is redacted ([BLOCKED: …]) wherever it would re-enter a prompt.
• Frontend-configurable — all settings exposed through five cards in the dsh settings UI, apply live.
• Optional human review before write — flip one setting (confirmBeforeWrite) and every extraction and tool write becomes a proposal in a pending queue (repeated signals accumulate hits and float up); adopting applies it (with your edits), rejecting discards it. The model never self-promotes: a proposed change to an existing entry rewrites nothing until you accept it.
• Memory manager UI — a dedicated "Memory" section in the dsh settings UI with three tabs: Overview (health dashboard), Review (the pending-proposal queue), and Manage — scope and workspace filters, BM25 search, category chips, a lazily loaded entry list, plus full write actions (edit / pin / archive / delete) — in English and Chinese.
• Time-window browsing + smart list view — memory_list returns newest-first with earliest/latest/hasStale metadata, accepts since/until epoch-ms bounds so "what did we learn last week" pages within the window, and suggests widening the filter when a narrowed query comes back empty over a non-empty store.
• Optional summaries for progressive disclosure — memory_add/memory_replace accept a summary, and extraction can emit a [summary:…] tag; index mode and auto-recall render summaries instead of truncated content.