🧠 Elite Longterm Memory

The ultimate memory system for AI agents. Combines 5 proven approaches into one bulletproof architecture.

flowchart TB
  subgraph ELITE["🧠 Elite Longterm Memory"]
    direction LR
    HOT["🔥 Hot RAM
SESSION-STATE.md
survives compaction"]
    WARM["🌡️ Warm Store
LanceDB vectors
semantic search"]
    COLD["🧊 Cold Store
Git-notes graph
permanent decisions"]
  end
  MEM["📖 MEMORY.md + daily/
curated · human-readable"]
  HOT --> MEM
  WARM --> MEM
  COLD --> MEM

┌─────────────────────────────────────────────────────────────────┐
│                    ELITE LONGTERM MEMORY                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐             │
│  │   HOT RAM   │  │  WARM STORE │  │  COLD STORE │             │
│  │             │  │             │  │             │             │
│  │ SESSION-    │  │  LanceDB    │  │  Git-Notes  │             │
│  │ STATE.md    │  │  Vectors    │  │  Knowledge  │             │
│  │             │  │             │  │  Graph      │             │
│  │ (survives   │  │ (semantic   │  │ (permanent  │             │
│  │  compaction)│  │  search)    │  │  decisions) │             │
│  └─────────────┘  └─────────────┘  └─────────────┘             │
│         │                │                │                     │
│         └────────────────┼────────────────┘                     │
│                          ▼                                      │
│                  ┌─────────────┐                                │
│                  │  MEMORY.md  │  ← Curated long-term           │
│                  │  + daily/   │    (human-readable)            │
│                  └─────────────┘                                │
└─────────────────────────────────────────────────────────────────┘

The 5 Memory Layers

Layer 1: Hot RAM (SESSION-STATE.md)

Active working memory that survives compaction. Uses Write-Ahead Log protocol.

# SESSION-STATE.md — Active Working Memory

## Current Task
[What we're working on RIGHT NOW]

## Key Context
- User preference: ...
- Decision made: ...
- Blocker: ...

## Pending Actions
- [ ] ...

Rule: Write BEFORE responding. If you respond first and crash, context is lost.

Layer 2: Warm Store (LanceDB Vectors)

Semantic search across all memories. Auto-recall injects relevant context.

# Auto-recall (happens automatically)
memory_recall query="project status" limit=5

# Manual store
memory_store text="User prefers dark mode" category="preference" importance=0.9

Layer 3: Cold Store (Git-Notes Knowledge Graph)

Structured decisions, learnings, and context. Branch-aware and tamper-evident.

# Store a decision (SILENT - never announce)
python3 memory.py -p $DIR remember '{"type":"decision","content":"Use React"}' -t tech -i h

# Retrieve context
python3 memory.py -p $DIR get "frontend"

Layer 4: Curated Archive (MEMORY.md + daily/)

Human-readable long-term memory. Daily logs plus distilled wisdom.

workspace/
├── MEMORY.md              # Curated long-term (the good stuff)
└── memory/
    ├── 2026-07-04.md      # Daily log
    ├── 2026-07-03.md
    └── topics/            # Topic-specific files

Layer 5: Cloud Backup (Optional)

Cross-device sync via SuperMemory API. Chat with your knowledge base from anywhere.

The WAL Protocol

Write-Ahead Log: Write state BEFORE responding, not after.

Trigger	Action
User states preference	Write to SESSION-STATE.md → then respond
User makes decision	Write to SESSION-STATE.md → then respond
User gives deadline	Write to SESSION-STATE.md → then respond
User corrects you	Write to SESSION-STATE.md → then respond

Why? If you respond first and crash/compact before saving, context is lost. WAL ensures durability.

← Back to Neo