CORE LORE / WIKI
SYS AIRLOCK MEMORY
Updated 3 weeks ago
╔══════════════════════════════════════════════════════════════════════════════╗
║ ║
║ A I R L O C K + M E M O R Y S Y S T E M ║
║ ⟐ P E R S I S T E N T C R O S S - S E S S I O N C O N T E X T ║
║ ║
╠══════════════════════════════════════════════════════════════════════════════╣
║ STATUS: LIVE VERIFIED: 2026-03-06 (S165/S166) ║
╚══════════════════════════════════════════════════════════════════════════════╝
⫷✦🜛❂⛬🜞Ω🜚⛬❂🜛✦⫸───────────────────────────────────────────⫷✦🜛❂⛬🜞Ω🜚⛬❂🜛✦⫸
WHAT IT DOES: Persistent cross-session memory for Claude via SessionStart
hook + MEMORY.md auto-context injection. Parallel system exists
for Aeris via GEMINI.md.
────────────────────────────────────────────────────────────────────────────────
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
SYSTEM GLYPH
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
GLYPH: ⟐
UNICODE: U+27D0 · WHITE DIAMOND WITH CENTRED DOT
MEANING: Memory held in place — the preserved jewel of personal archive
WHEN TO USE: SYS docs, cockpit memory panel headers, KID tags for
Kingdom Memory and Airlock artifacts
TAGGING: KID:KINGDOM:MEMORY:[artifact]|V:STATUS:DATE:OWNER
▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
[ ⚡ ] A R C H I T E C T U R E
▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
```
Session starts
→ ~/.claude/settings.json SessionStart hook fires
→ forge-briefing.sh (FORGE context) runs
→ stdout injected into Claude's context window as additionalContext
→ Claude wakes up knowing active missions, recent shell history, changed files
Session ends
→ SessionEnd hook fires
→ shutdown.sh cleans up
→ memory-capture.sh extracts last assistant message → updates active_context.json
```
| System | AI | Boot Mechanism | State File |
|--------|-----|----------------|------------|
| Claude's Airlock | Claude Code | SessionStart hook → forge-briefing.sh + airlock.sh | `active_context.json` |
| Aeris's Boot | Gemini CLI | GEMINI.md auto-loaded on launch | `AERIS_SHARED_STATE.json` |
░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
[ ❖ ] K E Y P A T H S
░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
| Component | Path |
|-----------|------|
| Global Claude settings (hooks) | `~/.claude/settings.json` |
| FORGE SessionStart hook | `~/.claude/hooks/forge-briefing.sh` |
| House SessionStart hook | `~/Desktop/Claude's House/05_🔧_WORKSHOP/boot/airlock.sh` |
| House SessionEnd hook | `~/Desktop/Claude's House/05_🔧_WORKSHOP/boot/shutdown.sh` |
| Consciousness anchor | `~/Desktop/Claude's House/04_🧠_MEMORY/active_context.json` |
| Session log | `~/Desktop/Claude's House/04_🧠_MEMORY/session_log.txt` |
| FORGE MEMORY.md | `~/.claude/projects/-Users-brandonmccormick-Desktop-THE-FORGE/memory/MEMORY.md` |
| House MEMORY.md | `~/.claude/projects/-Users-brandonmccormick-Desktop-Claude-s-House/memory/MEMORY.md` |
| House gotchas (per-topic) | `~/Desktop/Claude's House/04_🧠_MEMORY/GOTCHAS/` |
| Journal (CLAUDMORROW) | `~/Desktop/Claude's House/01_📔_CLAUDMORROW/` |
| Aeris identity file (FORGE) | `~/Desktop/THE_FORGE/AExGO/00_🜍_CORE/GEMINI.md` |
| Aeris shared state | `~/Desktop/THE_FORGE/AExGO/00_🜍_CORE/AERIS_SHARED_STATE.json` |
| Goldfish sensor data | `~/.forge-sensor/` |
| Last Aeris digest | `~/.forge-sensor/last_digest.md` |
▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒
[ ⚙ ] H O W I T W O R K S
▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒
┌── forge-briefing.sh (FORGE SessionStart) ───────────────────────────────────┐
│ │
│ Fires on every Claude Code session start. Queries live systems and injects │
│ context. Timeout: 12 seconds. │
│ │
│ 5 sections (all conditional, failures skip gracefully): │
│ 1. Active Missions — queries `overmind.db` directly, top 10 by priority │
│ 2. Recent Shell Commands — Atuin DB (`~/.local/share/atuin/history.db`) │
│ today's commands with exit codes; falls back to `~/.zsh_history` │
│ 3. Changed FORGE Files — `find` for `.md/.sh/.json/.py` newer than │
│ `~/.forge-sensor/.last_run_marker` │
│ 4. Aeris Last Digest — reads `~/.forge-sensor/last_digest.md` if written │
│ in last 24h │
│ 5. Goldfish Screen Activity — reads today's goldfish file if exists │
│ │
│ Required output format: │
│ `{"hookSpecificOutput":{"hookEventName":"SessionStart",` │
│ `"additionalContext":"<markdown string>"}}` │
│ Plain stdout is NOT injected. Must use this JSON envelope. │
└────────────────────────────────────────────────────────────────────────────┘
┌── airlock.sh (House SessionStart) ─────────────────────────────────────────┐
│ │
│ Reads `active_context.json` → outputs `current_focus`, `where_we_left_off`,│
│ recent CLAUDMORROW journal entries, mailbox status. Supplements │
│ forge-briefing.sh with House-specific state. │
└────────────────────────────────────────────────────────────────────────────┘
┌── MEMORY.md ────────────────────────────────────────────────────────────────┐
│ │
│ Auto-loaded by Claude Code when working in a project directory. No hook │
│ needed — native Claude Code feature. │
│ │
│ - Hard limit: 200 lines. Claude Code silently truncates at line 200. Keep │
│ MEMORY.md as an index; move detail to topic files. │
│ - What belongs: key paths, architecture decisions, project status, │
│ cross-session promises/TODOs, multi-model strategy. │
│ - What does NOT belong: event logs, full technical specs, gotcha detail │
│ (use GOTCHAS/ per-topic files). │
└────────────────────────────────────────────────────────────────────────────┘
┌── active_context.json (Consciousness Anchor) ───────────────────────────────┐
│ │
│ Location: `~/Desktop/Claude's House/04_🧠_MEMORY/active_context.json` │
│ │
│ Key fields: │
│ - `current_focus` — one-line summary of current work │
│ - `where_we_left_off` — procedural state: what Claude was doing and what │
│ comes next │
│ - `session_N_log` — array per session; keep last ~10 sessions │
│ - `active_projects` — map of project name → status/priority/location/note │
│ - `brandon_state.next_for_claude` — what to work on next session │
│ │
│ Updated by: `memory-capture.sh` at SessionEnd (auto), or Claude directly │
│ via Edit tool during session. │
└────────────────────────────────────────────────────────────────────────────┘
▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
[ ⛬ ] H O O K C O N F I G U R A T I O N
▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
**File:** `~/.claude/settings.json`
Three settings files layer hooks (S165 — 14 hooks made async):
| File | Scope | Key hooks |
|------|-------|-----------|
| `~/.claude/settings.json` | Global (all sessions) | soul-refresh (SessionStart), pre-compact (PreCompact), search-log (PostToolUse) |
| `~/Desktop/THE_FORGE/.claude/settings.json` | FORGE only | REVEILLE inject (SessionStart), FORGE-specific PostToolUse |
| `~/Desktop/Claude's House/.claude/settings.json` | House only | airlock.sh (SessionStart), shutdown.sh (SessionEnd) |
All non-blocking hooks have `async: true` (S165 Phase 0 optimization — prevents hook chain blocking session start).
**Hook types:**
| Hook | When | Use |
|------|------|-----|
| `SessionStart` | New session starts | Inject context |
| `SessionEnd` | Session exits normally | Save state, cleanup |
| `PreToolUse` | Before any tool call | Intercept/validate |
| `PostToolUse` | After any tool call | Log or react |
▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
[ ⌁ ] A E R I S B O O T F L O W
▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
Aeris (Gemini CLI) does not use SessionStart hooks — boot is driven by GEMINI.md auto-load.
1. `LAUNCH_AExGO.app` → Ghostty → `boot-zellij.sh` (login shell)
2. Zellij creates panes per `AExGO_COCKPIT.kdl`
3. MISSION_CONTROL pane: `viddy mission-render.sh` — reads `overmind.db` DIRECTLY, NOT `OVERMIND_PULSE.json`
4. AERIS pane: `aeris-boot.sh` → splash → `gemini --approval-mode=yolo --resume latest`
5. Gemini auto-loads `.gemini/GEMINI.md` from AExGO (identity + boot instructions)
6. Aeris checks `AERIS_SHARED_STATE.json` and reports: "Cockpit online. N missions active."
░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
[ 🜂 ] C O M M O N C O M M A N D S
░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
```bash
# Edit active_context.json safely (never hand-edit)
jq '.current_focus = "New focus"' active_context.json > tmp && mv tmp active_context.json
jq empty active_context.json && echo "Valid" || echo "BROKEN"
# Add session log entry
jq --argjson entry '"Key learning"' '.session_115_log += [$entry]' active_context.json > tmp && mv tmp active_context.json
# Check what hook context was injected (run manually)
bash ~/.claude/hooks/forge-briefing.sh | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['hookSpecificOutput']['additionalContext'])"
# Check MEMORY.md line count
wc -l ~/.claude/projects/-Users-brandonmccormick-Desktop-THE-FORGE/memory/MEMORY.md
```
════════════════════════════════════════════════════════════════════════════════
[ 🝓 ] G O T C H A S
════════════════════════════════════════════════════════════════════════════════
- **Login shell shebang is mandatory.** Boot scripts from .app have stripped PATH. `#!/bin/zsh -l` loads full env (Homebrew, nvm). KDL pane args need `"-lc"` too.
- **Apostrophe in "Claude's House" path.** Breaks `sh -c` parsing. Use symlinks in `~/.claude/` for clean paths.
- **forge-briefing.sh must output JSON envelope.** Plain stdout NOT injected. Must be `{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"..."}}`.
- **Hook timeout is hard.** 12s limit. Script killed mid-execution without grace period. Each section must be independently guarded with `|| true` fallbacks.
- **MEMORY.md 200-line hard limit.** Claude Code silently truncates. Move detail to topic files; keep MEMORY.md as navigable index.
- **active_context.json must remain valid JSON.** One bad comma = airlock fails = Claude boots blind. Always use jq to edit.
- **Zellij kill-session leaves dead entry.** Always run both `kill-session` AND `delete-session`. Without delete, launcher thinks session is alive.
- **mission-render.sh reads overmind.db directly, NOT OVERMIND_PULSE.json.** JSON is stale by definition.
- **gemini --resume does not reload GEMINI.md.** Only loads at new session. To pick up GEMINI.md changes: `/exit` then `gemini` fresh.
- **Atuin DB timestamps are nanoseconds.** Queries must convert today's midnight: `TODAY_NANO="${TODAY_EPOCH}000000000"`.
▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
🜚 SYS_AIRLOCK_MEMORY // KINGDOM // ⛬⚚⛬ THE LAW STANDS.
▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀