Neuroscience Inspired Memory
The memory system draws from a 2025 Science paper (Joo & Frank) that revealed how the hippocampus actually selects which memories to consolidate. The brain does not replay everything equally during sleep. During the day, the hippocampus fires "awake sharp-wave ripples" that bookmark important moments. During sleep, bookmarked memories compete for consolidation, with only the strongest patterns winning transfer to the neocortex.
The key insight: memory selection and memory consolidation are separate processes. Selection (tagging) happens during active work. Consolidation (storage) happens during sleep. Getting consolidation right is not enough if the system has no way to distinguish a critical architectural decision from a routine file read.
| Brain Mechanism | dreamcontext Feature |
|---|---|
| Hippocampus (working memory) |
state/ files (active tasks, sleep state) |
| Neocortex (long-term storage) |
core/ files (soul, user, memory), knowledge/ files |
| Awake sharp-wave ripples |
bookmark add (tag moments for consolidation) |
| Neural competition (strongest win) | Salience scoring (critical bookmarks trigger consolidation) |
| Memory decay (unused synapses weaken) | Knowledge access tracking (staleness indicators at 30+ days) |
| Sleep rhythm (every night) | Session count rhythm (advisory every 5 sessions) |
| Spreading activation | Warm knowledge tier (recently accessed files get first-paragraph preview) |
| Prospective memory ("do X when Y") | Contextual triggers (remind about X when task Y is active) |
| Hippocampal filtering | Transcript distillation (structural filter keeps signal, discards noise) |
| Sleep consolidation | RemSleep cycle (compressed replay into core files) |
| Inhibitory neurons | Anti-bloat pass (~150-line ceiling on core files, prune stale knowledge) |
| Synaptic plasticity | LIFO ordering (recent info surfaces first) |
| Immune system (error correction) | PostToolUse hook (auto-format + tsc check on every edit) |
| Attention gating | PreToolUse hook (blocks noisy exploration when curated context exists) |
| Persistent neural signals | UserPromptSubmit hook (undismissable debt reminders) |
| Autobiographical memory logging | PreCompact hook (audit trail of context loss events) |
During active work, the agent calls bookmark add "<message>" -s <salience> to tag important moments. Three salience levels:
- 1 (notable): Useful pattern discovered, minor decision
- 2 (significant): Architectural decision, user preference, meaningful bug
- 3 (critical): Breaking change, fundamental constraint, non-negotiable rule
The SKILL.md teaches the agent when to auto-bookmark. The stop hook links bookmarks to their session. The sleep agent processes bookmarks first, in salience order. Critical bookmarks become must-consolidate items.
Knowledge files accumulate but not all remain relevant. The system tracks access via knowledge touch <slug>, recording when each file was last read and how often. Files not accessed in 30+ days get staleness indicators in the snapshot. The sleep agent uses access data during its anti-bloat pass: stale files are candidates for archival, frequently accessed files for pinning.
Between the knowledge index (just titles and tags) and pinned knowledge (full content), there is a warm tier. Files accessed in the last 7 days or with tags matching active tasks get their first paragraph loaded into the snapshot. The agent often has just enough context to decide whether to read the full file, without burning tokens loading everything.
The sleep agent creates triggers when it spots context-dependent decisions during consolidation. A trigger stores a "when" keyword and a "remind" message. During snapshot generation, triggers are matched against active task names, tags, and bookmark text. Matching triggers surface as contextual reminders at the top of the snapshot. Triggers auto-expire after a configurable number of fires (default 3) to prevent noise.
Raw JSONL transcripts can be tens of thousands of lines. The transcript distill command applies structural filtering (pure Node.js, no AI): keeps user messages, agent reasoning, Write/Edit calls, modifying Bash commands, bookmark calls, and errors. Discards Read results, Glob output, tool metadata, and subagent internals. The sleep agent calls this selectively for sessions that need deep analysis.