liu-longterm-memory（刘长期记忆）

Elite Longterm Memory 🧠

The ultimate memory system for AI agents. Combines 6 layers 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)            │
│                  └─────────────┘                                │
│                          │                                      │
│                          ▼                                      │
│                  ┌─────────────┐                                │
│                  │   Backup    │  ← zip / Git remote (optional) │
│                  │ zip / Gitee │                                │
│                  └─────────────┘                                │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

The 6 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: BACKUP (zip / Git Remote) — Optional

Cross-device sync and disaster recovery. Use the CLI commands:

zip Backup (简单快速)

npx liu-longterm-memory backup
# → Creates memory-backup-20260404-153022.zip

npx liu-longterm-memory restore memory-backup-20260404-153022.zip
# → Restores from backup

Git Remote Backup (推荐，支持版本历史)

npx liu-longterm-memory backup --git
# → Commits and pushes memory files to your Git remote

# Tip: Use Gitee for domestic users (国内推荐)
# git remote add origin https://gitee.com/your-username/my-memory

Benefits:

• Version history: Track how decisions evolved over time
• Cross-device sync: Pull on any machine
• Free: GitHub and Gitee both offer free private repos
• 国内直连: Gitee 无需代理

Layer 6: AUTO-EXTRACTION (LLM-Powered)

Automatic fact extraction from conversations using LLM. Two modes:

Mode A: Agent-Driven Extraction (零依赖，默认)

No external service needed. The agent follows these rules to auto-extract facts:

Mode B: LLM Batch Extraction (智谱免费模型，推荐)

Use ZhipuAI's free GLM-4-Flash model to batch-extract facts from conversation history. Zero cost.

Call the GLM-4-Flash chat completions endpoint with a system prompt:

"Extract structured facts from the conversation. Return JSON array: [{type, content, importance}]. Types: preference, decision, fact, deadline, correction."

Then write each extracted fact to the appropriate memory layer.

• Free: GLM-4-Flash 完全免费，在 https://bigmodel.cn/ 注册获取密钥
• Automatic: Extracts preferences, decisions, facts, deadlines
• 国内直连: No proxy needed
• 80% token reduction vs raw conversation history

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) — Optional

No API key required for core memory. Layers 1/3/4 (SESSION-STATE.md, Git-Notes, MEMORY.md) work without any key. LanceDB vector search is an optional enhancement.

Choose your embedding provider in your config file (~/.openclaw/openclaw.json or ~/.clawdbot/clawdbot.json):

Option A: ZhipuAI (国内推荐，免费额度充足)

{
  "memorySearch": {
    "enabled": true,
    "provider": "openai-compatible",
    "baseURL": "https://open.bigmodel.cn/api/paas/v4",
    "model": "embedding-3",
    "apiKeyEnv": "ZHIPUAI_API_KEY",
    "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
        }
      }
    }
  }
}

Register at https://bigmodel.cn/ to get your free key, then set the ZHIPUAI_API_KEY environment variable.

Option B: Local Ollama (完全免费，离线可用)

{
  "memorySearch": {
    "enabled": true,
    "provider": "openai-compatible",
    "baseURL": "http://localhost:11434/v1",
    "model": "nomic-embed-text",
    "apiKeyEnv": "",
    "sources": ["memory"],
    "minScore": 0.3,
    "maxResults": 10
  }
}

# Install and pull embedding model
ollama pull nomic-embed-text

Option C: Any OpenAI-Compatible API (通用方案)

Works with OpenAI, DeepSeek, Moonshot, 通义千问, or any service with an OpenAI-compatible /v1/embeddings endpoint.

{
  "memorySearch": {
    "enabled": true,
    "provider": "openai-compatible",
    "baseURL": "https://api.openai.com/v1",
    "model": "text-embedding-3-small",
    "apiKeyEnv": "OPENAI_API_KEY",
    "sources": ["memory"],
    "minScore": 0.3,
    "maxResults": 10
  }
}

Set the environment variable matching your apiKeyEnv config (e.g. OPENAI_API_KEY, DEEPSEEK_API_KEY, or DASHSCOPE_API_KEY).

Option D: Disabled (纯文件记忆，无需任何 Key)

{
  "memorySearch": {
    "enabled": false
  }
}

Memory still works via SESSION-STATE.md, MEMORY.md, Git-Notes, and daily logs — just without vector semantic search.

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 Backup

# Option 1: zip backup (one command)
npx liu-longterm-memory backup

# Option 2: Git remote backup (推荐，支持版本历史)
npx liu-longterm-memory backup --git

# Restore from backup
npx liu-longterm-memory restore memory-backup-20260404.zip

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 (Auto-Extraction)

For every user message, scan for extractable facts and act BEFORE responding (WAL):

1. Preference detected? → Write to SESSION-STATE.md + append to MEMORY.md ## Preferences + memory_store (importance=0.9)
2. Decision made? → Write to SESSION-STATE.md + append to MEMORY.md ## Decisions Log + Git-Notes (SILENTLY)
3. Deadline/date given? → Write to SESSION-STATE.md ## Key Context
4. Tech stack mentioned? → Append to MEMORY.md ## Projects
5. Correction received? → Update SESSION-STATE.md + log to memory/lessons.md
6. Other concrete detail? → Write to SESSION-STATE.md ## Key Context
7. Backup requested? (user says "备份" / "backup" / "save memory") → Run npx liu-longterm-memory backup (zip) or npx liu-longterm-memory backup --git (Git)

On Session End

1. Update SESSION-STATE.md with final state
2. Distill session facts into MEMORY.md (if worth keeping long-term)
3. Create/update daily log in memory/YYYY-MM-DD.md with:

- Tasks completed - Decisions made - Lessons learned - Action items for next session

1. (Optional) If significant changes were made, suggest: npx liu-longterm-memory backup

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
5. Run backup: npx liu-longterm-memory backup or npx liu-longterm-memory backup --git

The WAL Protocol (Critical)

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

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..."

Supported Embedding Providers

Any service with an OpenAI-compatible /v1/embeddings endpoint works. Tested providers:

Maintenance Commands

# Check memory health
npx liu-longterm-memory status

# Create zip backup
npx liu-longterm-memory backup

# Git backup (commit + push)
npx liu-longterm-memory backup --git

# Restore from backup
npx liu-longterm-memory restore memory-backup-20260404.zip

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

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

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

# Check disk usage
du -sh ~/.openclaw/memory/       # or ~/.clawdbot/memory/
wc -l MEMORY.md
ls -la memory/

Why Memory Fails

Understanding the root causes helps you fix them:

Solutions (Ranked by Effort)

1. Quick Win: Enable memory_search

Enable semantic search with any OpenAI-compatible embedding provider:

openclaw configure --section web

This enables vector search over MEMORY.md + memory/*.md files. See the Enable LanceDB section above for provider configuration (ZhipuAI, Ollama, OpenAI, etc.).

2. LLM-Powered Auto-Extraction (Recommended)

Use the built-in auto-extraction rules (Layer 6) + optional LLM batch extraction with ZhipuAI's free GLM-4-Flash model. The agent scans each message for preferences, decisions, deadlines, and corrections, then writes them to the appropriate memory layer before responding. See Layer 6 for setup details.

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

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: → Verify your configured env var is set (check apiKeyEnv in config) → Verify memorySearch enabled in openclaw.json (or clawdbot.json) → Verify baseURL and model are correct for your provider

🇨🇳 国内用户指南

安装加速

# 使用 npmmirror 镜像加速安装
npx --registry https://registry.npmmirror.com liu-longterm-memory init

# 或全局设置镜像
npm config set registry https://registry.npmmirror.com

服务可用性

推荐配置（国内最佳实践）

1. 使用智谱AI或Ollama作为 embedding provider（见 Setup 章节）
2. 使用内置 Auto-Extraction + GLM-4-Flash（免费，国内直连）
3. 使用 zip 或 Gitee 远程仓库备份记忆文件
4. 通过国内镜像安装 npm 包

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
• ClawdHub 国内镜像: https://mirror-cn.clawhub.com

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