dsh-codex-memories
Codex-style long-term memory for DSH: cross-session memory that ingests finished sessions, consolidates them into a searchable handbook, and injects a compact summary before every turn.
It reproduces the two-stage structure of the Codex memory system rather than approximating it: per-session extraction first, then a consolidation pass over many raw memories.
Why
DSH sessions are isolated by default. A correction you made yesterday, a command that only works in one repo, a symptom/cause/fix you already paid for — none of it carries over unless you restate it. This plugin makes the agent remember:
- how you want it to work, without being told twice
- where the truth lives in a specific repo, and which commands actually run
- which failure has which fix
How it works
session goes idle for N seconds
└─ Stage 1 one model call per session -> session_summaries/<slug>.md + raw_memories.md
└─ Stage 2 once enough memory accumulates -> MEMORY.md + memory_summary.md
└─ before each turn, memory_summary.md is injected into the prompt
All durable artifacts are plain Markdown you can read, edit, version, or move. index.json holds the extraction cache, job records, and the consolidation watermark.
Install
dsh plugin --profile web add @lushdawn/dsh-codex-memories
Local development:
dsh plugin --profile web add link:<absolute path to this directory>
Restart DSH, or let a live profile hot-load it.
Commands
| Command | Effect |
|---|
/memory status | memory root, extracted sessions, pending consolidation, last timestamps |
/memory show | print the current memory_summary.md |
/memory extract | extract the current session immediately |
/memory backfill | scan stored sessions and extract the ones never processed |
/memory consolidate | merge pending memory into MEMORY.md now |
/memory forget <sessionId|all> | drop extraction records (handbook content is kept) |
/memory on / off | toggle automatic extraction for this process |
Tools
Exposed to the model when dedicatedTools is on:
| Tool | Effect |
|---|
memory_search | line-level keyword search across memory files (any / all / on_same_line) |
memory_read | read one memory file by line range |
memory_list | inventory of the memory folder and pending work |
memory_note | append one ad-hoc note — the only write path the model is offered |
The model is instructed to cite memory as MEMORY.md:12-14|note=[...].
Configuration
Every field has a safe default; override in your profile patch:
- insert:
- id: dsh-codex-memories
name: dsh-codex-memories
config:
storageDir: '' # default $DSH_HOME/memories
generate: true
use: true
dedicatedTools: true
model: '' # e.g. deepseek-official/deepseek-flash
extractModel: '' # falls back to model
consolidationModel: '' # falls back to model
idleSeconds: 120
maxSessionsPerRun: 3
maxSessionAgeDays: 30
consolidationThreshold: 2
maxInjectChars: 9000
minSessionMessages: 4
extractMaxTokens: 8000
consolidateMaxTokens: 16000
When model is empty the plugin reads the current default model, then falls back to deepseek-official/deepseek-flash.
Data layout
$DSH_HOME/memories/
├── MEMORY.md # durable handbook, Task Group organized
├── memory_summary.md # prompt-loaded layer; first line must be v1
├── raw_memories.md # mechanical stage-1 merge, ascending session id
├── session_summaries/<slug>.md # one structured recap per session
├── extensions/ad_hoc/notes/ # notes written by you or the model
└── index.json # extraction cache, job records, watermark
Cost and privacy
- It spends tokens: one Stage-1 call per session and one Stage-2 call per consolidation. Sessions under 4 messages are skipped; at most 3 sessions are processed per sweep.
- Local files only: no network access beyond the model API it calls.
- It enters your prompt:
memory_summary.md is injected every turn, which is why it is capped by maxInjectChars.
- Auditable: every artifact is readable Markdown.
- The model cannot rewrite the handbook: it may only append ad-hoc notes; consolidation is a separate pass, so one turn cannot corrupt durable memory.
Fidelity to Codex
The behavioral spec comes from reverse engineering Codex itself — the on-disk shape under ~/.codex/memories plus the prompt templates embedded in codex.exe:
| Codex | dsh-codex-memories |
|---|
~/.codex/memories/ | $DSH_HOME/memories/ |
MEMORY.md / memory_summary.md / raw_memories.md | same names, same formats |
rollout_summaries/*.md | session_summaries/*.md |
memories_1.sqlite | index.json |
| Stage 1 extraction prompt | PHASE1_TEMPLATE in lib/prompts.js |
| Phase 2 consolidation prompt | PHASE2_TEMPLATE in lib/prompts.js |
| usage guidance + citation format | USAGE_TEMPLATE in lib/prompts.js |
| rollout scan backfill | /memory backfill + boot sweep |
See docs/mechanism.md for the full mechanism and the evidence behind it.
Known limits
- Stage 2 asks for two complete documents in one reply. On a very large handbook the reply can hit the output cap; the old files are then kept and the pass reports an error instead of writing something corrupt.
- Automatic extraction needs the process alive during the idle window; otherwise the next boot's
backfill catches up.
- Retrieval is keyword/line based, not semantic — the same tradeoff Codex makes. Route with
keywords in MEMORY.md.
Contributing
Issues and pull requests are welcome — see CONTRIBUTING.md. For anything
security-related, follow SECURITY.md instead of opening a public issue. Release
history lives in CHANGELOG.md.
License
MIT
