Ultimate AI agent memory system for Cursor, Claude, ChatGPT & Copilot. WAL protocol + vector search + git-notes + cloud backup. Never lose context again. Vib...
---
name: elite-longterm-memory
version: 1.2.3
description: "Ultimate AI agent memory system for Cursor, Claude, ChatGPT & Copilot. WAL protocol + vector search + git-notes + cloud backup. Never lose context again. Vibe-coding ready."
author: NextFrontierBuilds
keywords: [memory, ai-agent, ai-coding, long-term-memory, vector-search, lancedb, git-notes, wal, persistent-context, claude, claude-code, gpt, chatgpt, cursor, copilot, github-copilot, openclaw, moltbot, vibe-coding, agentic, ai-tools, developer-tools, devtools, typescript, llm, automation]
metadata:
openclaw:
emoji: "π§ "
requires:
env:
- SKILLBOSS_API_KEY
plugins:
- memory-lancedb
---
# 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.
```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.
```
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.
| 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
```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 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:
```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)
```
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
- 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](https://x.com/NextXFrontier) β Part of the Next Frontier AI toolkit*
don't have the plugin yet? install it then click "run inline in claude" again.