Memory Directory & Four Types
Claude Code opera dois processos background: extraction per-turn (Layer 1) e consolidation cross-session (Layer 2 -- Dream). At query time, Recall seleciona memories relevantes.
~/.claude/projects/<slug>/memory/
MEMORY.md # index -- always in system prompt
user_role.md # topic files
feedback_testing.md
project_auth.md
.consolidate-lock # mtime == lastConsolidatedAt
logs/ # KAIROS/assistant-mode only
2026/03/2026-03-31.mdProfile, role, goals
Corrections + Why + How
Ongoing work, deadlines
External pointers
Layer 1: Extract Memories
No fim de cada query, handleStopHooks fires executeExtractMemories(). Usa forked agent pattern compartilhando prompt cache do parent.
Closure-Scoped State
let lastMemoryMessageUuid: string // cursor
let inProgress: boolean // overlap guard
let pendingContext: ... // stash for trailing run
let turnsSinceLastExtraction: number // throttle counterTwo-Turn Extraction Strategy
Mutual Exclusion
if (hasMemoryWritesSince(messages, lastMemoryMessageUuid)) {
logEvent('tengu_extract_memories_skipped_direct_write')
return // main agent already handled it
}
flowchart TD
A["handleStopHooks fires
executeExtractMemories()"] --> B{"inProgress?"}
B -->|"yes"| C["Stash context in pendingContext"]
B -->|"no"| D{"hasMemoryWritesSince
(main agent wrote)?"}
D -->|"yes"| E["Advance cursor
Skip fork"]
D -->|"no"| F["scanMemoryFiles()
Build manifest"]
F --> G["buildExtractAutoOnlyPrompt()"]
G --> H["runForkedAgent()
maxTurns=5"]
H --> I["Turn 1: parallel Read calls"]
I --> J["Turn 2: parallel Write/Edit calls"]
J --> K["Advance cursor"]
K --> L["extractWrittenPaths()"]
L --> M{"pendingContext?"}
M -->|"yes"| N["Run trailing extraction"]
M -->|"no"| O["appendSystemMessage:
Saved N memories"]
Layer 2: Auto Dream (Consolidation)
Fires via executeAutoDream() no fim do query-loop quando tres gates passam:
Gate 1: Time
Hours since lastConsolidatedAt >= 24h (default)
Gate 2: Sessions
Transcript files >= 5 sessions (default)
Gate 3: Lock
Nenhum outro processo mid-consolidation
Lock File Elegante
.consolidate-lock: body holds holder's PID. mtime IS lastConsolidatedAt -- ler o timestamp custa apenas um stat() call.
Consolidation -- 4 Phases
Recall: findRelevantMemories
At query time, Sonnet side-query seleciona ate 5 topic files relevantes.
Selecao
- Sonnet selector picks max 5 files
- Reads only first 30 lines (frontmatter range)
- Staleness caveat injected if > 1 day old
Tool Suppression
Se modelo esta usando tool ativamente (ex: mcp__X__spawn em recentTools), reference documentation desse tool e suprimida para evitar redundancia.
"This memory is 47 days old. Memories are point-in-time observations, not live state."
Team Memory Scope Routing
Scope routing per type e enforced via prompt guidance, nao filesystem permissions:
Always private
Default private; team only for project-wide conventions
Strongly bias toward team
Usually team
KAIROS Mode & Cache Efficiency
KAIROS / Assistant Mode
Sessoes longas usam append-only daily logs em logs/YYYY/MM/YYYY-MM-DD.md. Separate nightly /dream skill distila logs em topic files.
Cache Efficiency
Forked agent shares parent's prompt cache. Tool list deve match main agent para cache sharing -- tools sao parte da cache key.
AutoDream Gate Chain
flowchart TD
A["Post-sampling hook fires"] --> B{"isGateOpen?"}
B -->|"kairosActive"| X["Skip -- KAIROS uses disk-skill dream"]
B -->|"!autoMemEnabled"| Z["Skip"]
B -->|"pass"| C{"Time gate
hoursSince >= minHours?"}
C -->|"no"| Skip1["Return"]
C -->|"yes"| D{"Scan throttle
lastScanMs >= 10min?"}
D -->|"no"| Skip2["Return"]
D -->|"yes"| E["Scan sessions since lastConsolidatedAt"]
E --> F{"Session count >= minSessions?"}
F -->|"no"| Skip3["Return"]
F -->|"yes"| G["tryAcquireConsolidationLock"]
G -->|"null -- locked"| Skip4["Return"]
G -->|"priorMtime"| H["registerDreamTask UI"]
H --> I["runForkedAgent -- dream prompt"]
I --> J["completeDreamTask
appendSystemMessage"]