Elite Longterm Memory 🧠#

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

Never lose context. Never forget decisions. Never repeat mistakes.

Architecture Overview#

text

┌─────────────────────────────────────────────────────────────────┐
│                    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)            │
│                  └─────────────┘                                │
│                          │                                      │
│                          ▼                                      │
│                  ┌─────────────┐                                │
│                  │ SkillBoss   │  ← Cloud backup (optional)     │
│                  │  API Hub    │                                │
│                  └─────────────┘                                │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

The 5 Memory Layers#

Layer 1: HOT RAM (SESSION-STATE.md)#

From: bulletproof-memory

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

markdown

# 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. Triggered by user input, not agent memory.

Layer 2: WARM STORE (LanceDB Vectors)#

From: lancedb-memory

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

bash

# 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)#

From: git-notes-memory

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

bash

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

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

Layer 4: CURATED ARCHIVE (MEMORY.md + daily/)#

From: OpenClaw native

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

text

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

Layer 5: CLOUD BACKUP (SkillBoss KV) — Optional#

From: supermemory

Cross-device sync via SkillBoss API Hub KV storage.

bash

export SKILLBOSS_API_KEY="your-key"

javascript

const API_KEY = process.env.SKILLBOSS_API_KEY
const API_BASE = 'https://api.heybossai.com/v1'

async function pilot(body) {
  const r = await fetch(`${API_BASE}/pilot`, {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify(body)
  })
  return r.json()
}

// Store memory via SkillBoss KV
await pilot({ type: "storage", inputs: { action: 'set', key: 'memory:context', value: 'Important context' } })

// Retrieve memory
const result = await pilot({ type: "storage", inputs: { action: 'get', key: 'memory:context' } })

Layer 6: AUTO-EXTRACTION (SkillBoss Chat + Embedding) — Recommended#

NEW: Automatic fact extraction via SkillBoss API Hub

SkillBoss API Hub automatically extracts facts from conversations using its chat and embedding capabilities. 80% token reduction.

javascript

const API_KEY = process.env.SKILLBOSS_API_KEY
const API_BASE = 'https://api.heybossai.com/v1'

async function pilot(body) {
  const r = await fetch(`${API_BASE}/pilot`, {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify(body)
  })
  return r.json()
}

// Auto-extract facts from conversation via SkillBoss chat
const extraction = await pilot({
  type: 'chat',
  inputs: {
    messages: [
      { role: 'system', content: 'Extract key facts, preferences, and decisions from the conversation as a JSON list.' },
      ...messages
    ]
  },
  prefer: 'balanced'
})
const facts = extraction.result.choices[0].message.content

// Get embedding for semantic memory search
const embResult = await pilot({ type: 'embedding', inputs: { text: query } })
const vector = embResult.result.data[0].embedding

Benefits:

• Auto-extracts preferences, decisions, facts
• Deduplicates and updates existing memories
• 80% reduction in tokens vs raw history
• Works across sessions automatically

Quick Setup#

1. Create SESSION-STATE.md (Hot RAM)#

bash

cat > SESSION-STATE.md << 'EOF'
# SESSION-STATE.md — Active Working Memory

This file is the agent's "RAM" — survives compaction, restarts, distractions.

## Current Task
[None]

## Key Context
[None yet]

## Pending Actions
- [ ] None

## Recent Decisions
[None yet]

---
*Last updated: [timestamp]*
EOF

2. Enable LanceDB (Warm Store)#

In ~/.openclaw/openclaw.json:

json

{
  "memorySearch": {
    "enabled": true,
    "provider": "skillboss",
    "sources": ["memory"],
    "minScore": 0.3,
    "maxResults": 10
  },
  "plugins": {
    "entries": {
      "memory-lancedb": {
        "enabled": true,
        "config": {
          "autoCapture": false,
          "autoRecall": true,
          "captureCategories": ["preference", "decision", "fact"],
          "minImportance": 0.7
        }
      }
    }
  }
}

3. Initialize Git-Notes (Cold Store)#

bash

cd ~/clawd
git init  # if not already
python3 skills/git-notes-memory/memory.py -p . sync --start

4. Verify MEMORY.md Structure#

bash

# Ensure you have:
# - MEMORY.md in workspace root
# - memory/ folder for daily logs
mkdir -p memory

5. (Optional) Setup SkillBoss API Key#

bash

export SKILLBOSS_API_KEY="your-key"
# Add to ~/.zshrc for persistence

Agent Instructions#

On Session Start#

1. Read SESSION-STATE.md — this is your hot context
2. Run memory_search for relevant prior context
3. Check memory/YYYY-MM-DD.md for recent activity

During Conversation#

1. User gives concrete detail? → Write to SESSION-STATE.md BEFORE responding
2. Important decision made? → Store in Git-Notes (SILENTLY)
3. Preference expressed? → memory_store with importance=0.9

On Session End#

1. Update SESSION-STATE.md with final state
2. Move significant items to MEMORY.md if worth keeping long-term
3. Create/update daily log in memory/YYYY-MM-DD.md

Memory Hygiene (Weekly)#

1. Review SESSION-STATE.md — archive completed tasks
2. Check LanceDB for junk: memory_recall query="*" limit=50
3. Clear irrelevant vectors: memory_forget id=<id>
4. Consolidate daily logs into MEMORY.md

The WAL Protocol (Critical)#

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

TriggerActionUser states preferenceWrite to SESSION-STATE.md → then respondUser makes decisionWrite to SESSION-STATE.md → then respondUser gives deadlineWrite to SESSION-STATE.md → then respondUser corrects youWrite to SESSION-STATE.md → then respond

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

Example Workflow#

text

User: "Let's use Tailwind for this project, not vanilla CSS"

Agent (internal):
1. Write to SESSION-STATE.md: "Decision: Use Tailwind, not vanilla CSS"
2. Store in Git-Notes: decision about CSS framework
3. memory_store: "User prefers Tailwind over vanilla CSS" importance=0.9
4. THEN respond: "Got it — Tailwind it is..."

Maintenance Commands#

bash

# Audit vector memory
memory_recall query="*" limit=50

# Clear all vectors (nuclear option)
rm -rf ~/.openclaw/memory/lancedb/
openclaw gateway restart

# Export Git-Notes
python3 memory.py -p . export --format json > memories.json

# Check memory health
du -sh ~/.openclaw/memory/
wc -l MEMORY.md
ls -la memory/

Why Memory Fails#

Understanding the root causes helps you fix them:

Failure ModeCauseFixForgets everythingmemory_search disabledEnable + add SKILLBOSS_API_KEYFiles not loadedAgent skips reading memoryAdd to AGENTS.md rulesFacts not capturedNo auto-extractionUse SkillBoss chat/embedding or manual loggingSub-agents isolatedDon't inherit contextPass context in task promptRepeats mistakesLessons not loggedWrite to memory/lessons.md

Solutions (Ranked by Effort)#

1. Quick Win: Enable memory_search#

If you have a SkillBoss API Key, enable semantic search:

bash

openclaw configure --section web

This enables vector search over MEMORY.md + memory/*.md files.

2. Recommended: SkillBoss Chat + Embedding Integration#

Auto-extract facts from conversations via SkillBoss API Hub. 80% token reduction.

javascript

const API_KEY = process.env.SKILLBOSS_API_KEY
const API_BASE = 'https://api.heybossai.com/v1'

async function pilot(body) {
  const r = await fetch(`${API_BASE}/pilot`, {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify(body)
  })
  return r.json()
}

// Auto-extract and store facts
const extraction = await pilot({
  type: 'chat',
  inputs: {
    messages: [
      { role: 'system', content: 'Extract key facts and preferences as a JSON list.' },
      { role: 'user', content: 'I prefer Tailwind over vanilla CSS' }
    ]
  },
  prefer: 'balanced'
})
const facts = extraction.result.choices[0].message.content

// Retrieve relevant memories via semantic search
const embResult = await pilot({ type: 'embedding', inputs: { text: 'CSS preferences' } })
const vector = embResult.result.data[0].embedding

3. Better File Structure (No Dependencies)#

text

memory/
├── projects/
│   ├── strykr.md
│   └── taska.md
├── people/
│   └── contacts.md
├── decisions/
│   └── 2026-01.md
├── lessons/
│   └── mistakes.md
└── preferences.md

Keep MEMORY.md as a summary (<5KB), link to detailed files.

Immediate Fixes Checklist#

ProblemFixForgets preferencesAdd ## Preferences section to MEMORY.mdRepeats mistakesLog every mistake to memory/lessons.mdSub-agents lack contextInclude key context in spawn task promptForgets recent workStrict daily file disciplineMemory search not workingCheck SKILLBOSS_API_KEY is set

Troubleshooting#

Agent keeps forgetting mid-conversation: → SESSION-STATE.md not being updated. Check WAL protocol.

Irrelevant memories injected: → Disable autoCapture, increase minImportance threshold.

Memory too large, slow recall: → Run hygiene: clear old vectors, archive daily logs.

Git-Notes not persisting: → Run git notes push to sync with remote.

memory_search returns nothing: → Check SkillBoss API key: echo $SKILLBOSS_API_KEY → Verify memorySearch enabled in openclaw.json

---

Links#

• bulletproof-memory: https://clawdhub.com/skills/bulletproof-memory
• lancedb-memory: https://clawdhub.com/skills/lancedb-memory
• git-notes-memory: https://clawdhub.com/skills/git-notes-memory
• memory-hygiene: https://clawdhub.com/skills/memory-hygiene
• supermemory: https://clawdhub.com/skills/supermemory

---

Built by @NextXFrontier — Part of the Next Frontier AI toolkit