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
┌─────────────────────────────────────────────────────────────────┐
│ 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.
# 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.
# 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.
# 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.
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.
export SKILLBOSS_API_KEY="your-key"
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.
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)
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:
{
"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)
cd ~/clawd
git init # if not already
python3 skills/git-notes-memory/memory.py -p . sync --start
4. Verify MEMORY.md Structure
# Ensure you have:
# - MEMORY.md in workspace root
# - memory/ folder for daily logs
mkdir -p memory
5. (Optional) Setup SkillBoss API Key
export SKILLBOSS_API_KEY="your-key"
# Add to ~/.zshrc for persistence
Agent Instructions
On Session Start
- Read SESSION-STATE.md — this is your hot context
- Run
memory_search for relevant prior context
- Check memory/YYYY-MM-DD.md for recent activity
During Conversation
- User gives concrete detail? → Write to SESSION-STATE.md BEFORE responding
- Important decision made? → Store in Git-Notes (SILENTLY)
- Preference expressed? →
memory_store with importance=0.9
On Session End
- Update SESSION-STATE.md with final state
- Move significant items to MEMORY.md if worth keeping long-term
- Create/update daily log in memory/YYYY-MM-DD.md
Memory Hygiene (Weekly)
- Review SESSION-STATE.md — archive completed tasks
- Check LanceDB for junk:
memory_recall query="*" limit=50
- Clear irrelevant vectors:
memory_forget id=<id>
- Consolidate daily logs into MEMORY.md
The WAL Protocol (Critical)
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.
Example Workflow
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
# 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 Mode | Cause | Fix |
|---|
| Forgets everything | memory_search disabled | Enable + add SKILLBOSS_API_KEY |
| Files not loaded | Agent skips reading memory | Add to AGENTS.md rules |
| Facts not captured | No auto-extraction | Use SkillBoss chat/embedding or manual logging |
| Sub-agents isolated | Don't inherit context | Pass context in task prompt |
| Repeats mistakes | Lessons not logged | Write to memory/lessons.md |
Solutions (Ranked by Effort)
1. Quick Win: Enable memory_search
If you have a SkillBoss API Key, enable semantic search:
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.
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)
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
| Problem | Fix |
|---|
| Forgets preferences | Add ## Preferences section to MEMORY.md |
| Repeats mistakes | Log every mistake to memory/lessons.md |
| Sub-agents lack context | Include key context in spawn task prompt |
| Forgets recent work | Strict daily file discipline |
| Memory search not working | Check 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
Built by @NextXFrontier — Part of the Next Frontier AI toolkit
