Memory that
survives every session

Every session produces signals — a "remember this", a correction, a debugging session where repeated failures finally succeed. dsh-memory collects those signals, distills them into entries via an LLM, and pushes them through a security gate into a durable KV store; in the next session, the retrieval plane hands the relevant ones back into the context. Memories that keep getting used stay fresh; the neglected ones quietly fade out.

In practice it is seven Cordis composition rows: six functional plugins, each with one job — memory-store opens the storage domain and registers the ctx.memory service; tool-memory exposes the nine model tools; memory-review drives automatic extraction; memory-context manages system-prompt injection; memory-notes renders conventions and pitfalls into the project-notes prompt section (it writes no files into your repo); memory-remote backs the memory manager in the settings UI (remote writes default to off and must be enabled explicitly) — plus a no-op memory-root entry that exists only for client-module discovery. The storage medium is a single file, ~/.dsh/storages/memory.json — uninstalling the plugins never loses your memories.

Every user message and tool result flows through a zero-LLM-cost projection accumulator (session-projection). It collects just three kinds of candidate fragments — the collection layer deliberately keeps the funnel wide; the conservatism about what is worth keeping is the extraction prompt's job: a missed signal costs a little, a false one costs almost nothing.

The store ships one more layer: cross-process single-writer detection. The host storage backend assumes one writer per process — two DSH processes sharing a storage root each hold their own in-memory authoritative state and republish the whole unit file, silently clobbering each other. So on every boot, memory-store writes an owner stamp (pid + bootId) into the domain's global slot and re-reads it periodically: if its own stamp comes back as someone else's, a concurrent publisher exists and is reported at once. It detects, never locks — a foreign stamp whose pid is dead, or one closed cleanly, is no live threat, so restarts stay silent.

Retrieval in two steps: structured filtering first (scope / category / projectName), then BM25 scoring over the surviving candidates. The tokenizer splits Latin text by word and strips one conservative rule suffix to collapse inflections — uses→use, studies→study, while stems like class and basis are never damaged (one shared tokenizer for documents and queries); for CJK it emits single-character unigrams plus adjacent bigrams — the bigrams tighten matches, the unigrams keep single-character queries recallable. Summaries join the index alongside content, so a short summary recalls the entry too. Ranking proceeds by: relevance ↓, pinned ↓, recency ↓.

Each session freezes a memory snapshot at creation time and reuses it for the whole session — that keeps the KV-cache prefix stable: same prefix, full cache hits. The only moment it is broken is compaction (the prompt is being rebuilt anyway), and memories learned mid-session are injected exactly there. The snapshot has a dual budget: 5000 characters + 20 entries, with a trailing ≈N tokens estimate so injection cost is always visible.

Index mode — the factory default since 0.8 — is the core of progressive disclosure: each entry renders as a one-line existence index (scope/category · id · summary), ordered by the project → user → global relevance tier; when the budget runs out, the tail collapses into per-category counts (project/convention ×12) — index size grows with the number of categories, not entries. The model sees "what exists" and fetches full text with memory_get on demand.

Optional step-level auto recall takes a different road: on each agent step, a BM25 search keyed on that step's user text appends the hit entries as a fenced <recalled-memory> user message — the system prompt is untouched, the prefix cache does not move a single byte. On load, corrected entries carry a conflict annotation (⚠ conflicts with a newer correction) so the model weighs old vs. new itself.

The counterpart to decay is distillation: every 20 sessions, the curator picks oversized entries (≥ 400 chars) — at most 5 per pass — and has the LLM rewrite them into a concise single line; low-frequency, budget-constrained, and it can enter the human-review queue too. The memory store thus forgets, and it distills.

Flip on confirmBeforeWrite and the system's trust model changes completely: every extraction and tool write is downgraded to a proposal in the pending queue. The same proposal observed repeatedly accumulates hits and floats to the top — frequency is the signal. A human can edit before adopting, or reject with one click; a proposed change to an existing entry never touches the original before adoption. The model never self-promotes.

Finally, memories flow back into every session: convention / preference entries and the failure / procedure / tool-quirk pitfall log render into the project-notes system-prompt section. Nothing is written into your repository — memory lives in the host-side store and is managed in the Memory settings UI (since 0.6; the ≤0.5.x in-repo notes files are cleaned up automatically). Entries already rendered into notes are excluded from the memory section — the same content never appears twice in the prompt. The store is the source of truth; the notes section is its read-only projection.