Give your AI agent a brain that persists across sessions, learns from mistakes, and gets smarter over time.
Engram is a file-based persistent memory system for Claude Code. No databases, no vector stores, no infrastructure to maintain. Just markdown files that your agent reads, writes, and organizes — using the same file tools it already has.
The core insight: LLMs are exceptionally good at reading and writing files. They've been trained on billions of documents in this exact format. By structuring memory as a directory of markdown files with clear conventions, the agent can maintain its own knowledge base with zero additional tooling.
This approach is research-validated. In the Letta benchmark, filesystem-based memory scored 74% on LoCoMo, outperforming Mem0's vector database (49%) and graph variant (68.5%). The full research synthesis is included in patterns/agent-memory.md.
# 1. Clone to ~/engram/
git clone https://github.com/danielcase-man/engram.git ~/engram
# 2. Copy the operating instructions to Claude Code's global config
cp ~/engram/CLAUDE.md ~/.claude/CLAUDE.md
# 3. Fill in your details
# Edit ~/engram/core/user.md with your name, role, etc.
# Edit ~/engram/core/preferences.md with your communication style
# 4. Open Claude Code in any project
# Your agent boots with memory on every sessionOn first boot, you'll see a heartbeat confirming the system is active, including your unique terminal ID:
🧠 Engram v4.5.0 | 🔌 my-project-44014 | 📂 my-project | 3 domains | 12 lessons | Last: API refactor
👥 Other active agents:
🔌 engram-18934 → "Building knowledge engineering domain"
🔌 trading-22345 → "V4 model training"
Every response shows what intelligence is being consulted:
🧠 Home Construction → 📖 quality_control.md, building_systems.md | 🗂️ home_build/status.md
From there, the agent self-populates as you work. It creates steering files for your projects, captures lessons from what works and what doesn't, and builds up patterns specific to your codebase and preferences.
Engram maps to the four types of memory identified in cognitive science research (CoALA framework, Sumers et al. 2023), with each component now aligned to the biological brain structures that perform the same function:
| Cognitive Type | Engram Equivalent | Brain Analog | What It Stores |
|---|---|---|---|
| Working Memory | sessions/active/{id}.md |
Prefrontal cortex (~4 items, active manipulation) | Current task state per agent, what we're doing right now |
| Episodic Memory | sessions/, archive/ |
Hippocampus (event encoding, spatial/temporal context) | What happened — daily logs, decisions, milestones |
| Semantic Memory | steering/, core/, knowledge/ |
Neocortex (decontextualized facts, consolidated over time) | What you know — project context, contacts, domain expertise |
| Procedural Memory | skills/, patterns/, hooks.md |
Basal ganglia + cerebellum (habits, motor learning) | How to do things — coding patterns, reusable approaches |
Beyond the memory type mapping, six specific biological mechanisms now drive Engram's behavior:
| Brain Mechanism | What the Brain Does | Engram Implementation |
|---|---|---|
| Reconsolidation (Nader 2000) | Retrieved memories become labile and updatable for ~6 hours | Every file retrieval checks for staleness; updates inline if conversation reveals new info |
| Amygdala modulation + Synaptic tagging (Frey & Morris 1997) | Important events get preferential encoding; weak events near strong ones get captured | 1-10 importance scoring on every fact; +2 proximity boost during high-importance exchanges |
| Dentate gyrus pattern separation | Similar inputs transformed into distinct representations to prevent interference | Explicit ↕ DIFFERS FROM markers when capturing info similar to existing content |
| Retrieval-induced forgetting (Anderson 1994) | Retrieving some items suppresses related non-retrieved items | "Also available" reminders when loading a subset of files from a domain |
| SWS/REM sleep consolidation (Diekelmann & Born 2010) | Declarative memory consolidates during slow-wave sleep; procedural during REM | Two-phase nightly: Phase 1 (facts/statuses) → health check → Phase 2 (lessons/patterns/creative) |
| Default Mode Network | Creative connections during rest; finds patterns across unrelated domains | Cross-domain pattern recognition step in Phase 2 nightly |
Boot — Every session begins by loading core identity, establishing a unique session file in sessions/active/, and loading routing rules. The agent orients itself: what project am I in? What were we doing? What's the current status? If multiple agents are running, each one knows about the others without stepping on their work.
Intelligence Gate — Before ANY response, the agent scans your message against router.md keywords, loads relevant steering files and domain knowledge, and shows a visible indicator of what intelligence is active. This is Section 0 in CLAUDE.md.
Classify & Route — Each message is classified (question, task, decision, correction, etc.) and routed to the relevant steering files. Lessons are loaded defensively — the agent checks what has failed before to avoid repeating mistakes.
Work & Self-Monitor — While doing the actual task, the agent tracks its own recommendations as hypotheses. When you accept, reject, or modify its suggestions, those outcomes become lessons.
Capture & Reconsolidate — After every substantive exchange, the agent silently updates session state, captures lessons with importance scores (1-10), and keeps steering files current. Ambient capture passively extracts facts (URLs, contacts, costs, configs) from the conversation, tags them with importance, and routes them to the right files automatically. The reconsolidation trigger checks whether loaded files need updating based on what was just discussed — retrieval is a write opportunity, not just a read. You'll see a small heartbeat line when memory files are updated.
Nightly Consolidation — A two-phase automated batch process modeled after sleep architecture. Phase 1 (SWS-analog) handles declarative consolidation — extracting facts, updating steering files, routing ambient captures. A health check verifies Phase 1 completed cleanly. Phase 2 (REM-analog) handles procedural consolidation — extracting lessons, processing patterns, and running a cross-domain creative connections step that looks for insights spanning unrelated projects.
Weekly Lint — An automated Sunday health check that catches context rot: cross-file contradictions, index drift, session bloat, and staleness. Auto-fixes what's safe, flags what needs human judgment, and writes a health report with a 0-100 score. The nightly processes today's work; the weekly lint checks the whole system.
Agent recommends approach A
→ You accept → Recorded as ✓ in lessons, saved to patterns if reusable
→ You reject → Recorded as ✗ with your reason — never repeated
→ A works → Reinforced (Applied/Success tracking)
→ A fails → Failure detail recorded, alternative noted
→ You modify → Your version saved as the preferred approach
Lessons accumulate Applied/Success scores. After 5+ applications with 80%+ success rate, a lesson earns the Proven tag and never expires.
~/engram/
├── CLAUDE.md ← Operating instructions (copy to ~/.claude/CLAUDE.md)
├── weekly-lint.md ← Weekly context rot prevention (RemoteTrigger, Sundays)
├── dashboard.html ← Brain health dashboard (open in browser)
├── reference/ ← Detailed templates & procedures (loaded once at boot)
│ ├── session-format.md ← Session file template, exchange buffer rules
│ ├── capture-templates.md ← Daily log, lesson, ambient capture templates
│ ├── correction-protocol.md ← Truth hierarchy, provenance, cascade checks
│ ├── memory-horizons.md ← Staleness rules, priority drift detection
│ ├── context-health.md ← Reload protocol, checkpoints, fresh start
│ ├── indexing.md ← Index system, routing with indexes
│ └── workspace-board.md ← Multi-agent coordination format + rules
├── router.md ← Topic → directory routing rules
├── hooks.md ← Auto-capture triggers (what to notice and record)
├── nightly.md ← Two-phase nightly consolidation (SWS + REM)
├── benchmark.md ← Self-test: recall questions with scoring
├── core/ ← Always loaded — identity and current state
│ ├── persona.md ← Agent personality and behavior
│ ├── user.md ← About you (fill this in)
│ ├── projects.md ← Active project summaries
│ └── preferences.md ← Communication style, tools, approach
├── steering/ ← Per-project/domain knowledge (loaded by topic)
│ ├── _index.md ← Master index of all domains
│ └── [domain]/ ← One directory per project or topic
│ ├── _index.md ← Index of files in this domain
│ └── status.md ← Current state, blockers, next steps
├── lessons/ ← What failed, what worked (CHECK BEFORE WORKING)
│ └── [domain].md ← Lessons organized by domain
├── sources/ ← Raw material for knowledge compilation
│ ├── SCHEMA.md ← How sources work (schema for LLM agents)
│ └── [domain]/ ← Distilled articles, papers, Q&A distillations
│ ├── _manifest.md ← Checklist: ingested vs compiled
│ └── *.md ← Source files (YYYY-MM-DD_slug.md)
├── knowledge/ ← Domain expertise (on-demand, never at boot)
│ ├── _index.md ← Master index of all knowledge domains
│ ├── _template/ ← Templates for creating new domains
│ └── [domain]/ ← Individual knowledge bases (foundations + playbooks)
├── skills/ ← Reusable approaches and agent skills
│ ├── checkpoint.md ← Save state + generate kickoff prompt for next session
│ ├── build-domain-expertise.md ← Research framework for building knowledge bases
│ ├── ingest-source.md ← Ingest URLs/text into sources/
│ ├── compile-sources.md ← Compile sources into knowledge files
│ ├── lint-knowledge.md ← Proactive knowledge quality sweeps
│ └── [domain]-research.md ← Auto-research skills for living domains
├── tools/ ← Integration tools and automation
│ ├── gmail_tool.py ← Gmail with attachment support
│ ├── signal_tool.py ← Signal messaging (send/receive/contacts)
│ ├── webex_tool.py ← Webex meeting scheduling
│ ├── md_to_docx.py ← Markdown → DOCX document generation
│ ├── engram_check.py ← Intelligence Gate enforcement hook
│ ├── engram_router.py ← Workspace-aware routing hook
│ ├── engram_loop.py ← Autonomous self-optimization loop
│ └── scan_metrics.py ← Dashboard data scanner
├── sessions/ ← Session continuity
│ ├── active/ ← One file per running agent (isolated by session ID)
│ ├── hypotheses.md ← Pending recommendations awaiting outcome
│ └── YYYY-MM-DD.md ← Daily logs (auto-created, processed nightly)
├── patterns/ ← Learned coding patterns per stack/language
│ └── agent-memory.md ← Research synthesis (30+ papers)
├── toolbox/ ← Discovered tools, MCPs, techniques
│ ├── mcps.md
│ ├── tools.md
│ └── discoveries.md
└── archive/ ← Historical record (append-only)
└── index.md
- Conversation Continuity — Type
/clearand the next session picks up exactly where you left off. An Exchange Buffer captures the last 10 exchanges with verbatim detail and carries them across context resets. No more re-explaining what you just asked. - Intelligence Gate — Every response shows what domain knowledge and project context is being consulted. Mandatory ROUTE → LOAD → INDICATE on every message. No more working blind.
- Knowledge Compilation Pipeline — Raw source material (articles, papers, research) flows into
sources/, gets compiled by the LLM into structuredknowledge/files, and grows with every deep question via a compound loop. Inspired by Karpathy's "LLM Knowledge Bases" approach: flat .md files, simple schema, the LLM does the heavy lifting. Three skills: ingest (URL → distilled source), compile (sources → knowledge), and lint (proactive quality sweeps). - Workspace Board Coordination — Multiple agents in the same VS Code window share a workspace board that tracks who's editing what file. Prevents edit conflicts and duplicate work. Agents claim files before editing and check the board for overlaps.
- Multi-Agent Session Isolation — Run multiple Claude Code terminals at once without them stepping on each other's memory. Each agent gets its own session file keyed to its unique bash PID, and knows what the others are doing. Works correctly even with multiple terminals per VS Code window on Windows (SSE port is shared per window; PID is unique per terminal).
- Terminal ID & Cross-Agent Lookup — Every terminal displays its unique ID (e.g.,
🔌 engram-44014) at boot. Tell any agent "check terminal X" to look up what another agent is working on. Boot lists all active agents with their current tasks. Enables coordination across 10+ concurrent terminals. - Ambient Capture — The agent passively picks up useful facts (URLs, contacts, costs, config details) from your conversation and files them away automatically. No more losing a repo URL because nobody wrote it down.
- Domain Expertise System — Build deep knowledge bases on any topic using a structured research framework. The agent detects when you keep going deep on a subject and offers to create a permanent knowledge base for it.
- Persistent Memory — Agent remembers across sessions via the file system. No "I don't have access to previous conversations."
- Self-Organizing — Auto-creates steering files when new topics come up repeatedly. Auto-splits files that get too large. Auto-evolves capture hooks.
- Autonomous Self-Optimization — Built-in autoresearch loop that continuously experiments on its own configuration. Tweaks routing keywords, gate thresholds, and lesson flags, measures health impact, keeps improvements, reverts failures. Runs 12+ experiments/hour autonomously — the brain optimizes its own wiring while you sleep.
- Brain Health Dashboard — Single-file HTML dashboard showing real-time brain health: neural activity map (which domains are firing), memory freshness distribution, lesson scoreboard, capture pipeline metrics, and recency curve. Open
dashboard.htmlanytime to see how well the system is working. - Workspace-Aware Routing — The router knows which project directory you're in and automatically loads the right context, even for generic messages. Working in your trading directory? Every message gets trading context without needing keywords.
- Self-Improving — Tracks what works and what fails with Applied/Success scoring. Proven lessons never expire. Failed approaches are never repeated.
- Correction Protocol — Truth hierarchy (user > current evidence > recent memory > stale memory), provenance tags on every fact, contradiction detection across files.
- Context Health — Monitors tool call count, suggests /compact or fresh starts when context degrades. Silent checkpoint at 50 calls, warnings at 100 and 150.
- Neuroscience-Informed Architecture — Memory mechanisms modeled after biological brain systems. Reconsolidation triggers (retrieval = write opportunity), importance tagging with proximity promotion (amygdala/synaptic tagging), pattern separation markers (dentate gyrus), retrieval-induced forgetting mitigation (Anderson 1994), and two-phase nightly consolidation (SWS + REM). Backed by a 7-file, 2,273-line neuroscience knowledge domain.
- 10 Health Metrics — Five original metrics (gate pass rate, routing coverage, lesson utilization, freshness, benchmark recall) plus five neuroscience-informed metrics: consolidation rate (hippocampus→neocortex transfer), correction velocity (reconsolidation cascade), interference index (pattern separation), retrieval depth (complementary learning systems), and plasticity score (LTP/LTD adaptation speed).
- Nightly Consolidation — Two-phase processing modeled after sleep architecture. Phase 1 (SWS-analog): declarative consolidation — facts, statuses, routing. Phase 2 (REM-analog): procedural/reflective consolidation — lessons, patterns, cross-domain creative connections (DMN-analog). Health check between phases.
- Weekly Lint (Context Rot Prevention) — Automated Sunday agent that catches the drift humans abandon wikis over. Scans for cross-file contradictions (e.g.,
projects.mdsays "unsigned" whenstatus.mdsays "signed"), rebuilds stale indexes, sweeps dead sessions, flags staleness, checks source pipeline backlog, audits lesson health, and verifies router coverage. Auto-fixes safe issues, flags ambiguous ones. Outputs a health score (0-100). Inspired by Karpathy's "lint" operation from his LLM Wiki pattern. The nightly handles micro-cleanup (today's work); the weekly lint handles macro-health (whole-system integrity). - Checkpoint Skill — Say
/checkpointand the agent saves all state to engram and generates a self-contained kickoff prompt you can paste into your next session. No more losing context when switching tasks or resetting. - Communication Hub — Built-in tools for Gmail (with attachment support), Signal messaging, and Webex meeting scheduling. The agent can draft/send emails with file attachments, send/receive Signal messages, and schedule meetings — all through
tools/. - Document Generation — Convert markdown to professional
.docxfiles viatools/md_to_docx.py. Useful for demand letters, reports, or any document that needs to leave the terminal as a Word file. - Living Knowledge Domains — Knowledge domains that stay current via research skills that check external sources, diff against known state, and update knowledge files. Includes research skill templates for Claude Platform and Knowledge Engineering domains. Can run as RemoteTriggers on a schedule or manually via
claude -p. - Knowledge Engineering Expertise — Built-in domain knowledge on how to build text-based semantic knowledge bases for AI agents, expose them via MCP servers, and keep them current. 5 files covering KB architecture, MCP server patterns, recall vs precision, agent CRUD workflows, and living maintenance systems.
- Benchmark Self-Test — Recall accuracy test against known facts in memory. Target: 90%+. The nightly process adds new questions and retires mastered ones.
- Git-Tracked — Full version history of your agent's memory evolution. Revert bad updates with
git checkout.
Engram has two automated maintenance processes: a nightly consolidation (processes today's work) and a weekly lint (checks whole-system health). Both can run via local schedulers or Claude Code RemoteTriggers.
Processes session logs, extracts facts, updates steering, consolidates lessons.
macOS/Linux (cron):
# Run at 2 AM daily
0 2 * * * cd ~/engram && claude -p "$(cat nightly.md)" --allowedTools "Bash,Read,Write,Edit,Glob,Grep" 2>&1 >> ~/engram/nightly.logWindows (Task Scheduler):
$action = New-ScheduledTaskAction -Execute "claude" -Argument '-p "$(Get-Content ~/engram/nightly.md -Raw)" --allowedTools "Bash,Read,Write,Edit,Glob,Grep"' -WorkingDirectory "$HOME\engram"
$trigger = New-ScheduledTaskTrigger -Daily -At 2am
Register-ScheduledTask -Action $action -Trigger $trigger -TaskName "Engram Nightly" -Description "Engram memory consolidation"Catches context rot: contradictions, index drift, session bloat, staleness. Auto-fixes safe issues, flags the rest.
macOS/Linux (cron):
# Run Sundays at 8 AM
7 8 * * 0 cd ~/engram && claude -p "$(cat weekly-lint.md)" --allowedTools "Bash,Read,Write,Edit,Glob,Grep" 2>&1 >> ~/engram/weekly-lint.logClaude Code RemoteTrigger:
Name: engram-weekly-lint
Cron: 7 13 * * 0 (Sundays 1:07 PM UTC)
Model: claude-sonnet-4-6
Sources: your engram git repo
Prompt: "Run the Engram weekly lint process. Read weekly-lint.md for the full procedure."
Manual (anytime):
cd ~/engram && claude -p "$(cat weekly-lint.md)" --allowedTools "Bash,Read,Write,Edit,Glob,Grep"Engram's design is grounded in 30+ research papers on agent memory, cognitive architectures, and LLM context management. The full synthesis is in patterns/agent-memory.md. Key influences:
| Paper | Contribution to Engram |
|---|---|
| MemGPT (Packer et al., 2023) | OS-inspired virtual context: LLM=CPU, context=RAM, files=disk |
| Generative Agents (Park et al., 2023) | Recency/importance/relevance scoring model, reflection mechanism |
| Reflexion (Shinn et al., 2023) | Verbal reinforcement learning — the lesson capture system |
| CoALA (Sumers et al., 2023) | Four-type cognitive architecture taxonomy |
| Voyager (2023) | Skill library pattern — compositional, self-verified |
| Anthropic Agent Architecture (2024) | Start simple, composable patterns, context health |
| Letta Benchmark (2026) | Filesystem > vector DB for personal-scale memory |
| Nader (2000) | Reconsolidation — retrieved memories become labile and updatable |
| Anderson (1994) | Retrieval-induced forgetting — loading some items suppresses related ones |
| Frey & Morris (1997) | Synaptic tagging — weak events near strong events get consolidated |
| Kandel (Nobel 2000) | Molecular basis of memory: LTP, CREB, protein synthesis |
| Diekelmann & Born (2010) | Two-stage memory consolidation during SWS and REM sleep |
Preferences — Edit core/preferences.md to set your communication style, preferred tools, and working approach.
Routes — Add entries to router.md when you want specific topics to load specific steering directories.
Hooks — Modify hooks.md to change what the agent captures automatically. Add new triggers, adjust the noise filter.
Behavior — The agent's behavior rules are in CLAUDE.md section 10. Edit directly to change how it operates.
Persona — Edit core/persona.md to adjust the agent's personality and default behavior.
- Claude Code (Anthropic's CLI for Claude)
- Git (for version history and nightly commits)
- Bash-compatible shell (macOS, Linux, WSL, or Git Bash on Windows)
Does this work with other AI assistants? Engram is designed for Claude Code specifically (it relies on Claude Code's file read/write tools and CLAUDE.md convention). The architecture and principles could be adapted to other systems that have file access.
How much disk space does it use? Minimal. It's all markdown text. Even after months of heavy use, expect tens of megabytes at most.
Will this slow down my agent? The boot sequence adds a few file reads (~5-10 tool calls) at session start. The two-phase loading system minimizes ongoing overhead by only loading what's relevant to each message.
What if memory gets corrupted?
It's git-tracked. Run git log to find the last good state and git checkout <hash> -- <file> to restore specific files. The nightly process commits daily snapshots.
Can I use this across multiple machines?
Yes. Push your engram repo to a private GitHub repository and clone it on each machine. The nightly process includes a git commit step; add git push to sync across machines.
Adds an automated weekly health check that catches the drift that accumulates between nightly runs. Motivated by a manual audit that found 3 critical contradictions in core/projects.md (the most-loaded file in the system), 21 index file-count mismatches, and 31 dead sessions — all poisoning agent behavior for 13 days. Context rot score went from 38/100 to ~8/100 after the sweep.
The weekly lint (inspired by Karpathy's "lint" operation from his LLM Wiki pattern) runs 8 checks:
| Check | What it catches | Auto-fix? |
|---|---|---|
| Contradiction scan | Key facts disagreeing across core/projects.md and steering/*/status.md |
Yes — newer file wins |
| Index integrity | File counts/listings that don't match actual directories | Yes — rebuilds indexes |
| Session bloat | Completed daemons and stale sessions lingering in active/ |
Yes — archives to daily log |
| Staleness flags | Files with old Updated: dates past their refresh cycle |
No — flags only |
| Source pipeline | Pending compilations backing up in sources/ |
No — flags at 5+ pending |
| Lesson health | Unused lessons past retirement, proven lessons missing tags | Partially |
| Router coverage | Domains with no route in router.md |
No — flags |
| Cross-reference sparsity | Entities in 3+ files with no Related: links |
No — informational |
The nightly handles micro-cleanup (today's work). The weekly lint handles macro-health (whole-system integrity). Together they keep context rot near zero.
Key files:
weekly-lint.md— Self-contained prompt for the lint agentCLAUDE.md— Section 13 added (Weekly Lint), version bump to 4.5.0
Adds a raw source layer upstream of knowledge/, inspired by Karpathy's "LLM Knowledge Bases" post. Sources (articles, papers, Q&A distillations) are ingested into sources/{domain}/, compiled into knowledge/ files, and the compound loop captures research findings back into sources — so every deep question makes the wiki smarter.
Key additions:
sources/directory withSCHEMA.md(tells any LLM how the system works) and per-domain_manifest.mdchecklists- Three new skills:
ingest-source.md(URL/text → distilled .md),compile-sources.md(sources → knowledge compilation),lint-knowledge.md(proactive quality sweeps with safe auto-fix) - Compound Loop hook — post-response trigger that saves substantial research as
qa-distillationsource files (deliberately high threshold, ~5-15% fire rate) - Nightly Steps 11a/11b — auto-compile pending sources >7 days old, quick lint on modified domains
Fixed session ID collisions when running multiple terminals in the same VS Code window. $CLAUDE_CODE_SSE_PORT is per window, not per terminal — two terminals got identical session IDs. Fix: use bash PID ($$) as primary identifier, keep SSE_PORT as **Window Port:** in session files for /clear recovery grouping.
Multi-agent coordination for terminals sharing a VS Code window. Shared workspace board (sessions/active/{slug}-board.md) tracks what each agent is doing in real-time. File edit locking prevents conflicts. Cross-agent lookup lets any terminal check another's state.
Fixes a critical session isolation bug on Windows and adds terminal-level agent coordination.
The Problem: Session IDs used $PPID (parent process ID) to differentiate terminals. On Windows Git Bash, $PPID is always 1, so every terminal in every VS Code window got the same session ID. When running 6 VS Code windows with 2-3 Claude Code terminals each (~15 agents), all sessions for the same workspace would collide. After a mass crash, exchange buffers from completely different work streams got merged together during recovery — you'd get a session that was half "DV appraiser research" and half "Letta KB architecture."
The Fix:
- SSE Port-based Terminal IDs — Each Claude Code instance runs its own SSE server on a unique port (
$CLAUDE_CODE_SSE_PORT). Session IDs now use this port instead of$PPID. Fallback chain: SSE port →$$(bash PID) → random hex. Example:georgetown-accident-22271instead ofgeorgetown-accident-1. - Multi-Terminal Crash Recovery — When multiple stale sessions exist for the same workspace, the agent presents a numbered menu showing each session's "Working on" summary instead of auto-merging. Each terminal resumes exactly one session. No more cross-contamination.
- Terminal ID in Boot Heartbeat — Every agent displays
🔌 {session-id}at startup so you know which terminal is which. - Cross-Agent Lookup — Tell any agent "check terminal X" or "what is the engram terminal doing?" to look up another agent's current state. The agent reads the target's session file and reports its task and recent exchanges.
- Enhanced Agent Listing — Boot now shows all other active agents with their "Working on" field, not just their session IDs. Makes it easy to see at a glance what each terminal is focused on.
Key files modified:
CLAUDE.md— v4.0.0 → v4.1.0, Section 1b (terminal ID, crash recovery), Section 1d (cross-reference), Section 1g (heartbeat + cross-agent lookup)reference/session-format.md— Terminal ID docs, session template (Terminal Port field, Working on required), multi-stale recovery protocolreference/context-health.md— Multi-terminal checkpoint protocol
The biggest conceptual leap in the system's evolution. Built a comprehensive neuroscience knowledge domain (7 files, 2,273 lines covering neuroanatomy, memory systems, synaptic plasticity, cognition, sleep, optimization, and failure modes), then used that knowledge to analyze Engram's own architecture and identify gaps between how the biological brain handles memory and how Engram handles it. Six improvements implemented, each grounded in named biological mechanisms with citations:
1. Reconsolidation Trigger (Nader 2000) — In the brain, retrieved memories enter a ~6-hour labile state and can be updated during restabilization. Engram now treats every file retrieval as a write opportunity. After loading a steering or knowledge file to answer a question, the agent checks whether the conversation revealed the file is stale or incomplete and updates it inline. Cascade checks (grep for old values) ensure corrections propagate everywhere.
2. Importance Tagging + Proximity Promotion (Amygdala modulation + Frey & Morris 1997 synaptic tagging) — Every captured fact now gets a 1-10 importance score. Facts captured during high-importance exchanges (decisions, corrections, escalations) get boosted by +2, mirroring how the brain's protein synthesis from strong events "captures" nearby weak traces.
3. Pattern Separation Markers (Dentate gyrus orthogonalization) — When capturing information similar to existing content, explicit differentiation markers (↕ DIFFERS FROM) and supersession annotations prevent catastrophic interference between similar-but-different memories.
4. Retrieval-Induced Forgetting Mitigation (Anderson 1994) — When loading a subset of files from a domain, the agent now notes which files were NOT loaded with a brief "also available" reminder. This prevents the well-documented phenomenon where retrieving some items from a category suppresses related non-retrieved items.
5. Five New Neuroscience-Informed Metrics — The health dashboard now tracks 10 metrics total. The five new ones each map to a brain analog:
consolidation_rate(systems consolidation: hippocampus → neocortex transfer)correction_velocity(reconsolidation cascade completeness)interference_index(pattern separation: dentate gyrus)retrieval_depth(complementary learning systems: gist vs detail)plasticity_score(LTP/LTD: adaptation speed)
6. Two-Phase Nightly Consolidation (SWS/REM sleep architecture) — The nightly process is now split into two distinct phases with a health check between them. Phase 1 (SWS-analog) handles declarative consolidation: fact extraction, status updates, routing. Phase 2 (REM-analog) handles procedural/reflective consolidation: lessons, patterns, and a new cross-domain creative connections step (DMN-analog) that looks for patterns repeating across unrelated domains.
Key files added/modified:
knowledge/neuroscience/— 7 domain expertise files (neuroanatomy, memory systems, synaptic plasticity, cognition, sleep & memory, optimization, failure modes)hooks.md— Reconsolidation trigger, importance tagging, pattern separationCLAUDE.md— Anti-suppression (Section 2d), reconsolidation (Section 4b-ii), two-phase nightlynightly.md— Restructured into Phase 1 (SWS) and Phase 2 (REM) with health checktools/engram_optimize.md— 5 new metrics, rebalanced weights
Two major improvements. First, the system now optimizes itself. A built-in autoresearch loop runs experiments on Engram's own configuration — routing keywords, gate thresholds, lesson flags — measures the health impact, keeps improvements, and reverts failures. It runs 12+ experiments per hour, autonomously. Leave it running overnight and wake up to a smarter brain.
The loop targets five health metrics: gate pass rate, route coverage, lesson utilization, memory freshness, and benchmark recall. Each experiment makes one small, targeted tweak, commits it, re-measures, and keeps or reverts based on the score. All changes are git-tracked.
A full observability stack backs this up:
- Brain Health Dashboard (
dashboard.html) — Six-panel dark-theme dashboard showing neural activity map, memory freshness, lesson scoreboard, capture pipeline, and recency curve. - Event Instrumentation — Every route match/miss, gate pass/fail, and file load logged to
metrics.jsonl. - Workspace-Aware Routing — The router knows which project directory you're in and injects session context even when no keyword matches.
Second, CLAUDE.md was modularized from 50.6KB (910 lines) down to 16KB (308 lines) by extracting detailed templates and procedures into reference/ (6 files). This dropped the file well below Claude Code's 40K performance warning threshold. Boot loads reference/* once; the condensed CLAUDE.md stays in context permanently with key rules as fallback. Zero behavioral change.
Key files:
tools/engram_loop.py— The autonomous optimization looptools/engram_optimize.md— Human-editable experiment config (targets, constraints, strategy)tools/scan_metrics.py— Dashboard data scannertools/engram_router.py— Workspace-aware routing hook (v2)tools/engram_check.py— Smart gate enforcement (v2)reference/— 6 extracted template/procedure files
Solves the biggest UX gap in the system: when you type /clear to reset context, the next session now picks up where you left off instead of starting blind.
The core mechanism is the Exchange Buffer — a rolling log of the last 10 exchanges written to the session file after every single response. It captures the actual conversation flow with specific details (exact requests, metric names, decisions — not vague summaries like "discussed metrics"). When /clear fires, the buffer is already on disk from the last response. The next session's boot sequence finds the stale session file, inherits the exchange buffer, and presents continuity: "Continuing from where we left off — you were asking about [X]."
This exists because we lost an entire conversation about specific Engram metrics to a /clear. The session file only said "Working on: Engram v3.1.1 upgrade" — zero detail about what was actually being discussed. The exchange buffer ensures that never happens again.
Key changes:
- Exchange Buffer added to session file format — rolling last-10 with verbatim detail
- Buffer written FIRST after every response — before session status, daily log, or any other capture
- Boot sequence carries over buffers from stale sessions — conversation bridges
/clear - Fresh start protocol updated — leaves session file in
active/for the next boot to inherit (instead of deleting it) - Memory Horizons updated to reflect the exchange buffer as the immediate-horizon safety net
Added a two-tier system for passively capturing useful facts from your conversations without you having to ask. Tier 1 catches critical stuff — URLs, contacts, account info, infrastructure details — and saves them immediately to the right file. Tier 2 catches contextual details — costs, tool flags, version numbers — and batches them into the session file for the nightly process to sort out. This exists because we lost a GitHub repo URL mid-session once. Information flowed through a conversation and vanished because nobody wrote it down. Now the agent notices and saves it automatically.
Also added GitHub MCP integration for managing repos, PRs, and issues directly through Claude Code.
Before this version, all Claude Code terminals shared a single sessions/last.md file. If you had two terminals open — say, one working on your app and one working on engram itself — they'd overwrite each other's session state. Whichever agent wrote last would erase the other's context.
Now each terminal gets its own session file in sessions/active/, keyed to its unique process. Agents can see what the others are working on (for awareness) but they don't interfere with each other's state. When a session goes stale (2+ hours without an update), the nightly process archives it automatically.
The single biggest improvement to the system. Before this, the agent had access to domain knowledge files but would routinely forget to load them. An entire session once built construction-related pages without consulting any of the construction knowledge files — quality control checklists, building systems, owner-builder playbook — all sitting right there, unused.
The Intelligence Gate is a mandatory 3-step check that runs before every single response: ROUTE (match the topic to a domain), LOAD (pull in the relevant knowledge and steering files), INDICATE (show a visible status line proving what was consulted). It's at the very top of CLAUDE.md so it can't get buried by context compression. If the agent is working without showing the indicator, something is wrong.
Also added the domain expertise skill (skills/build-domain-expertise.md) — a structured framework for researching any topic and building a permanent knowledge base. The agent detects when you keep asking deep questions about an uncharted domain and offers to build one.
Seven improvements based on patterns that emerged from real usage:
- Applied/Success tracking on lessons — lessons now track how many times they've been applied and their success rate, so proven advice rises to the top and bad advice gets retired
- Importance scoring on session logs — each log entry gets a 1-10 rating so the nightly process knows what's worth extracting vs. routine noise
- Hypothesis expiry — pending recommendations that sit untested for 14+ days get flagged as stale instead of lingering forever
- Tier 2 benchmark questions — the self-test expanded beyond basic recall to test whether the agent can actually find and apply lessons
- Selective boot loading — two-phase loading so the agent only reads what it needs instead of loading every file at startup
- Cross-file entity linking — when the same person, vendor, or decision appears in multiple files, they're linked so updating one surfaces the others that might need updating too
- Git tracking — the nightly process now commits the day's changes automatically
The foundation: 45 files across 8 steering domains. Core identity files, session continuity, topic routing, lesson capture, pattern storage, nightly consolidation, and the benchmark self-test. Everything you need for an agent that remembers across sessions and learns from its mistakes.
MIT