qui-elite-longterm-memory

Ultimate AI agent memory system for Cursor, Claude, ChatGPT & Copilot. WAL protocol + vector search + git-notes + cloud backup. Never lose context again. Vib...

Security Scan

The skill's requests and instructions generally match its stated purpose (a long‑term memory system) but there are a few small inconsistencies and clear privacy implications you should understand before enabling cloud features.

Purpose & Capability

The skill claims to provide layered long‑term memory (WAL, LanceDB vectors, git-notes, MEMORY.md, optional cloud backup). The only environment variable it requests is SKILLBOSS_API_KEY, which matches the documented optional SkillBoss cloud backup and auto-extraction functionality. The included CLI writes local memory files and checks for a LanceDB path — all coherent with the stated purpose.

Instruction Scope

SKILL.md explicitly instructs the agent to call SkillBoss APIs for cloud KV storage, chat-based fact extraction, and embeddings (examples show fetch to https://api.heybossai.com). That is coherent with the cloud backup/auto‑extraction feature, but it means conversation data, extracted facts, and embeddings will be sent to an external service. The SKILL.md also references plugins (memory-lancedb) and auto-recall behaviors that will cause automatic network or plugin calls; the file contains truncated sections ("…[truncated]") so there may be more runtime behavior not visible here.

Install Mechanism

No install spec is provided (instruction-only + small CLI file). The included bin/elite-memory.js only writes local markdown files and examines local paths; it does not download remote code or execute obscured installs. This is low-risk from an installation perspective.

Credentials

The single required env var (SKILLBOSS_API_KEY) is proportionate to the documented optional cloud backup and auto-extraction features. However, that key grants access to a remote API (SkillBoss) that the instructions use to store and extract memory; providing it will allow the skill to transmit conversation content and derived embeddings to that external service. No other unrelated credentials are requested.

Persistence & Privilege

The skill is not marked always:true and has normal user-invocable/autonomous invocation settings. It does not request persistent modifications to other skills or system configs. Its CLI creates local files in the workspace only.

Assessment

This skill appears to do what it says: local file-based memory plus optional cloud sync and auto‑extraction via SkillBoss. Before installing or providing SKILLBOSS_API_KEY, consider: 1) Privacy: the SKILL.md shows code that will send conversation text and embeddings to https://api.heybossai.com — don’t provide the API key if you plan to store sensitive PII, secrets, proprietary code, or client data. Use a scoped/minimal API key if possible. 2) Audit: the included CLI is simple and only writes local markdown files, but SKILL.md had truncated sections — review the full SKILL.md/README in your environment or upstream repo to ensure there are no unexpected behaviors. 3) Verify origin: registry metadata shows version 1.0.0 while SKILL.md/package.json say 1.2.3 and package.json lists a GitHub URL; confirm the repository and publisher are legitimate. 4) Least privilege: prefer creating a dedicated SkillBoss key with limited scope for memory storage/embedding rather than reuse of a broad account key. 5) If you do not want data sent externally, do not set SKILLBOSS_API_KEY and avoid enabling the auto‑extraction/cloud backup features; the local CLI still works for creating SESSION-STATE.md, MEMORY.md, and daily logs.

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

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

# 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

• 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