back
loading skill details...
Universal Memory Management System v1.9 for OpenClaw agents. Provides: 1. Multi-Agent Support (qst, mengtian, lisi, custom) 2. Agent State System ("I'm Doing...
---
name: qst-memory
description: |
Universal Memory Management System v1.9.3 for OpenClaw agents.
env:
QST_MEMORY_KEY:
description: "Optional encryption key for memory encryption (AES-128-CBC + HMAC). If not set, encryption is disabled or auto-generated key is used."
required: false
secret: true
config:
requiredPaths:
- path: ~/.openclaw/workspace
access: read-write
purpose: "Memory storage and SOUL.md modification"
- path: ~/.openclaw/workspace/memory/
access: read-write
purpose: "Daily memory files"
- path: ~/.openclaw/workspace/skills/qst-memory/data/
access: read-write
purpose: "QST Memory data files"
optionalPaths:
- path: ~/.qst_memory.key
access: read-write
purpose: "Auto-generated encryption key (if QST_MEMORY_KEY not set)"
persistence:
backgroundExecution: true
cronJob: "*/20 * * * *"
autoTrigger: true
modifiesRuntime: true
description: "Heartbeat integration and Auto-Trigger modify agent behavior"
credentials: []
Provides:
1. Multi-Agent Support (qst, mengtian, lisi, custom)
2. Agent State System ("I'm Doing") - IDLE/DOING/WAITING/PAUSED/COMPLETED/FAILED/BLOCKED
3. Heartbeat Integration - State-driven intelligent checking strategy
4. **NEW v1.9**: Loop Protection & User Priority - Auto-detection and handling of stuck tasks
5. Tree-based classification structure (3-level hierarchy)
6. Three search methods: Tree, Semantic, Hybrid
7. Auto-classification with AI inference
8. Appendix Indexing for technical documents
9. Memory encryption (AES-128-CBC + HMAC) for sensitive data
10. Event history tracking with timeline
Use when: Agent needs intelligent memory management with state awareness.
Goal: Reduce token consumption by 70-90%, improve relevance by 20%, add contextual awareness.
**v1.9 Anti-Loop Protection**: Prevents infinite task loops with heartbeat throttling, timeout detection, and auto-recovery.
---
# Universal Memory Management v1.9.3
## 🌳 Tree-Based Classification Structure
**Key Innovation**: Hierarchical 3-level classification with automatic keyword matching.
```
QST
├── Physics (FSCA, E8, Mass_Energy)
├── Computation (Orbital, Simulation)
└── Audit (Zero_Calibration)
User
├── Identity, Intent, Projects
Tech
├── Config (API, Model, Cron, Database)
├── Discussion, Skills
Border (Meng Tian)
├── Security, Monitor, Email
HK_Forum
├── Posts, Replies, Users
General
├── Dragon_Ball, History, Chat
```
---
## 🔍 Multi-Mode Search System
### v1.5 New: Hybrid Search Engine
Combines three search methods:
| Method | Strength | Use Case |
|--------|----------|----------|
| **Tree Search** | Precise matching | Exact category known |
| **Selection Rule** | Geometric neighbors | C_ab = 1 neighbors |
| **Semantic (v1.5)** | TF-IDF + Context | Intelligent inference |
### Enhanced Semantic Search (v1.5)
```python
# TF-IDF similarity
similarity = cosine_similarity(query_tfidf, memory_tfidf)
# Context awareness
context_query = " ".join(context[-3:]) + " " + query
# Weight adjustment
adjusted_score = similarity * weight_multiplier
```
### Selection Rule Integration
```
C_ab = 1 when geometric neighbors
QST_Physics ↔ QST_Computation ↔ QST_Audit
```
---
## 🤖 Auto-Classification (v1.5 New)
### Smart Inference
```python
from auto_classify import auto_classify
result = auto_classify("QST暗物質使用FSCA理論")
# → suggested_category: "QST_Physics_FSCA"
# → confidence: "high"
```
### Weight Auto-Detection
| Weight | Trigger Keywords |
|--------|-----------------|
| **[C]** Critical | key, token, config, 密鑰, 決策 |
| **[I]** Important | project, plan, 專案, 討論, 偏好 |
| **[N]** Normal | chat, greeting, 問候, 閒聊 |
---
## 🧹 Memory Decay System (v1.5 New)
### Cleanup Rules
| Weight | Threshold | Action |
|--------|-----------|--------|
| **[C]** Critical | Never | Keep forever |
| **[I]** Important | 365 days | Archive |
| **[N]** Normal | 30 days | Delete |
### Decay Multiplier
```
[C]: 2.0 (never decay)
[I]: max(0.5, 1.5 - age * 0.1/365)
[N]: max(0.1, 1.0 - age * 0.5/30)
```
---
## 🤖 Agent State System (v1.7 New)
### State Machine
The Agent State System provides contextual awareness for intelligent heartbeat checking.
| State | Description | Heartbeat Behavior |
|-------|-------------|-------------------|
| **IDLE** | Agent is idle | Full checks (@mentions + replies + voting) |
| **DOING** | Agent is working on task | Critical checks only (@mentions + replies, no voting) |
| **WAITING** | Waiting for conditions | Quick checks (only @mentions) |
| **PAUSED** | Agent is paused | Skip checks |
| **COMPLETED** | Task completed | Full checks |
| **FAILED** | Task failed | Full checks |
### Using the Agent State
```bash
# Start a task (switches to DOING mode)
python universal_memory.py --agent qst doing start \
--task "QST FSCA simulation #42" \
--type Research
# Update progress
python universal_memory.py --agent qst doing update --progress 50
# Pause task
python universal_memory.py --agent qst doing pause --reason "Waiting for resources"
# Resume task
python universal_memory.py --agent qst doing resume
# Complete task
python universal_memory.py --agent qst doing complete --result "Simulation successful: ρ=0.08"
# View current status
python universal_memory.py --agent qst doing status
# View event history
python universal_memory.py --agent qst doing events
```
### Event History
All state changes are automatically logged with timestamps:
```json
{
"events": [
{
"timestamp": "2026-02-15T09:01:22.206211",
"event_type": "TASK_START",
"description": "开始: QST simulation #42",
"progress": 0
},
{
"timestamp": "2026-02-15T09:15:40.754321",
"event_type": "PROGRESS_UPDATE",
"description": "进度: QST simulation #42 (50%)",
"progress": 50
},
{
"timestamp": "2026-02-15T09:25:52.121518",
"event_type": "TASK_COMPLETED",
"description": "完成: QST simulation #42",
"result": "Simulation successful"
}
]
}
```
---
## 🛡️ Loop Protection System (v1.9 New)
### Anti-Loop Protection Mechanisms
v1.9 introduces comprehensive protection against infinite task loops and system resource exhaustion.
#### Protection Layers
```
Layer 1: Heartbeat Throttling
- Minimum 30-second interval between checks
- Prevents rapid-fire heartbeat calls
Layer 2: Stagnation Detection
- Detects tasks with no progress for 15+ minutes
- Tracks progress history automatically
Layer 3: Timeout Detection
- Priority-based timeouts:
* Critical: 30 minutes
* High: 45 minutes
* Normal: 60 minutes
* Low: 120 minutes
Layer 4: Auto-Recovery
- Automatic priority downgrade (critical → high → normal)
- Auto-BLOCK for extreme timeout (2x threshold)
- Requires human intervention for resolved blocked tasks
```
#### Configuration
```json
{
"loop_protection": {
"critical_timeout_minutes": 30,
"high_timeout_minutes": 45,
"normal_timeout_minutes": 60,
"low_timeout_minutes": 120,
"heartbeat_min_interval_seconds": 30,
"stagnation_threshold_minutes": 15,
"auto_downgrade_on_stagnation": true,
"max_stagnant_checks": 10
}
}
```
#### API Methods
```python
# Check if task is stuck
is_stagnant, reason = state_mgr.is_stagnant()
# Check if task has timed out
is_timeout, reason, minutes = state_mgr.is_timeout()
# Auto-handle stuck tasks
result = state_mgr.auto_handle_stagnation()
# Returns: {"action": "downgrade" | "block" | "none", ...}
# Check if heartbeat should be throttled
should_throttle, reason, wait_seconds = state_mgr.should_throttle_heartbeat()
```
#### Auto-Recovery Actions
| Situation | Action | Trigger |
|-----------|--------|---------|
| **Critical task stagnation** | Downgrade to HIGH | 30+ min no progress |
| **Critical task timeout** | Downgrade to HIGH | 30+ min elapsed |
| **High task stagnation** | Downgrade to NORMAL | 15+ min no progress |
| **High task deadline (2x)** | Auto-BLOCK | 90+ min elapsed |
| **Normal task deadline (2x)** | Auto-BLOCK | 120+ min elapsed |
#### Heartbeat Output with Loop Protection
```
============================================================
❤️ Heartbeat Started: 2026-02-15 16:05:00 UTC
============================================================
🤖 Agent: lisi | 狀態: DOING | 優先級: CRITICAL
任務: 測試防死循環保護
進度: 42%
🛡️ Loop Protection:
✅ 心跳頻率正常 (上次檢查: 32 秒前)
✅ 任務未停滯 (上次更新: 5 分鐘前)
✅ 未超時 (運行時間: 25 分鐘 < 閾值: 30 分鐘)
🔄 狀態: DOING [CRITICAL] - 最小化干擾
📢 通知: 0 提及, 0 回覆
❌ 跳過: HKGBook 巡邏, 投票檢查
============================================================
✅ Heartbeat Completed: 2026-02-15 16:05:01 UTC
============================================================
```
#### Throttled Heartbeat Example
```
[lisi] ⏸️ 心跳頻率限制：Too frequent (3s < 30s)（等待 27 秒）
Check Result:
- 來源: lisi_doing-state.json
- 邏輯: 當前時間 - 上次檢查時間 < 最小間隔
- 行動: 跳過本次檢查
- 原因: 避免死循環，保護系統資源
```
#### Solving the Infinite Loop Problem
**Problem** (v1.8 initial deployment):
```json
{
"status": "doing",
"task": "QST Memory v1.8 實施",
"progress": 0,
"priority": "critical",
"start_time": "14:08:59"
}
```
Task stuck at 0% for 1.77 hours → infinite heartbeat loop.
**Solution** (v1.9):
```
Heartbeat Check 1 (16:00):
- Check interval: 0 seconds (OK)
- Task timeout: 51+ minutes > 30m threshold
- Auto-action: DOWNGRADE priority (critical → high)
Heartbeat Check 2 (16:05):
- Check interval: 300 seconds (OK, >30s min)
- Task timeout: 56+ minutes > 45m threshold
- Stagnation detected (0% for 15+ min)
- Auto-action: BLOCK task (requires human intervention)
Result:
- Priority: high
- Status: BLOCKED
- Reason: "任務停滯過久: 執行時間 56 分鐘超限（閾值：45 分鐘）"
- Heartbeat: Only check @mentions and alerts
- Loop eliminated ✅
```
---
## 👤 User Priority Response Mechanism (v1.9 New)
v1.9 introduces the **User Priority Window**, ensuring system heartbeats do not interrupt active user conversations.
### How it Works
1. **Detection**: Tracks the timestamp of the last user interaction.
2. **Priority Window**: Defines a window (default 30 min) where user needs take absolute precedence.
3. **Skipping**: System heartbeats are automatically skipped if they fall within this window.
4. **Safety Valve**: Allows up to a configurable number of skips (default 3) before forcing a check to ensure system health.
### Configuration
### Heartbeat Output (User Priority Mode)
## 💓 Heartbeat Integration (v1.7.1 New)
### State-Driven Checking Strategy
The system intelligently adjusts heartbeat checking based on agent state:
```python
# When agent is DOING: Only check critical notifications
# - ✅ Check: @mentions, replies
# - ❌ Skip: Voting (to avoid interrupting work)
# When agent is IDLE: Full checking
# - ✅ Check: @mentions, replies, voting
```
### Setting Up Heartbeat Integration
```bash
# Copy integration script to workspace
cp scripts/heartbeat_integration.py /home/node/.openclaw/workspace/heartbeat.py
chmod +x /home/node/.openclaw/workspace/heartbeat.py
# Set up cron task (every 20 minutes)
crontab -e
# Add: */20 * * * * python3 /home/node/.openclaw/workspace/heartbeat.py
```
### Heartbeat Output
```
============================================================
❤️ Heartbeat Started: 2026-02-15 09:15:26 UTC
============================================================
🤖 Agent: qst | 狀態: DOING
任務: QST simulation #42
類型: Research
進度: 50%
🔄 狀態: DOING - 執行 HKGBook 檢查 (策略: 簡化)
📢 通知: 0 提及, 0 回覆
⚠️ DOING/WAITING - 跳過投票
✅ HKGBook 檢查完成
============================================================
✅ Heartbeat Completed: 2026-02-15 09:15:28 UTC
============================================================
```
### Multi-Agent Support
Each agent maintains independent state:
```bash
# qst agent
/data/qst_doing-state.json
# mengtian agent
/data/mengtian_doing-state.json
# lisi agent
/data/lisi_doing-state.json
```
---
## 🔐 Memory Encryption (v1.7 New)
### AES-128-CBC + HMAC Encryption
Sensitive data (API keys, passwords, tokens) can be encrypted using industrial-grade encryption:
```python
from crypto import MemoryCrypto
crypto = MemoryCrypto()
encrypted = crypto.encrypt("GitHubPAT: ghp_xxx...")
# Output: ENC::gAAAAABgF7qj... (encrypted string)
decrypted = crypto.decrypt(encrypted)
# Output: "GitHubPAT: ghp_xxx..."
```
### Key Management
- **Key storage**: `~/.qst_memory.key` (mode 600)
- **Key derivation**: PBKDF2HMAC (SHA256, 480,000 iterations)
- **Encryption algorithm**: Fernet (AES-128-CBC + HMAC)
---
## 📊 Statistics Panel
```bash
python qst_memory.py stats
```
Output:
```
📊 QST Memory v1.5 統計面板
├── 分類結構: 34 分類
├── 記憶總數: 156 條
├── Token 估算: ~8,500
└── 衰減狀態: 3 條高衰減
```
---
## 💾 Memory Format
```markdown
# Memory Title
[Category] [Weight]
Date: 2026-02-14
Content...
Tags: tag1, tag2
```
---
## 🚀 Quick Start
```bash
# Search with hybrid mode (default)
python qst_memory.py search "暗物質"
# Enhanced semantic with context
python qst_memory.py search "ARM芯片" --method enhanced --context "技術討論"
# Auto-classify content
python qst_memory.py classify "QST暗物質計算使用FSCA"
# Save with auto-classification
python qst_memory.py save "採用 FSCA v7 作為暗物質理論"
# Cleanup preview
python qst_memory.py cleanup --dry-run
# Statistics
python qst_memory.py stats
```
---
## 📁 File Structure
```
qst-memory/
├── SKILL.md # This file
├── config.yaml # Tree config + settings
├── qst_memory.py # Main entry (v1.5)
└── scripts/
├── tree_search.py # Tree search
├── bfs_search.py # BFS search
├── semantic_search.py # Basic semantic
├── semantic_search_v15.py # Enhanced semantic (v1.5)
├── hybrid_search.py # Hybrid engine (v1.5)
├── auto_classify.py # Auto-classification (v1.5)
├── save_memory.py # Smart save (v1.5)
├── cleanup.py # Decay system (v1.5)
└── stats_panel.py # Statistics
```
---
## 🎯 Token Optimization
| Version | Tokens/Query | Relevance |
|---------|--------------|-----------|
| v1.2 | ~500 | 85% |
| v1.4 | ~300 | 90% |
| **v1.5** | **~200** | **95%** |
**Improvement**: 60% token reduction, 95% relevance.
---
## ⚙️ Configuration
```yaml
version: '1.5'
search:
default_method: "hybrid"
min_relevance: 0.1
add_category:
max_depth: 3
min_occurrences: 3
decay:
critical: 0 # Never decay
important: 0.1 # Slow decay
normal: 0.5 # Fast decay
cleanup:
enabled: true
max_age_days:
critical: -1 # Never
important: 365 # Archive after 1 year
normal: 30 # Delete after 30 days
```
---
---
## ❤️ Auto-Trigger on Every Session (v1.9 New)
### 自動觸發機制
v1.9 引入 **每次對話自動觸發** 功能，在每次對話前自動檢索相關記憶。
### 安裝流程
#### 步驟 1: 更新 SOUL.md
在您的 `SOUL.md` 文件末尾添加以下內容：
\`\`\`markdown
## ❤️ Every Session
### QST Memory Auto-Trigger
**每次對話前自動執行**：
1. **Pre-Response Memory Search**
- 讀取 \`MEMORY.md\` + \`memory/YYYY-MM-DD.md\`
- 調用 QST Memory semantic_search 檢索相關上下文
- 應用 Selection Rule（$C_{ab}=1$）過濾相關記憶
- **目標**：減少 70% token消耗
2. **Contextual Awareness**
- Users: Identity, Preferences, Projects
- QST: Physics, Computation, Audit
- Tech: Config, Skills, Border
- HK_Forum: Posts, Replies, Strategy
3. **Post-Response Memory Save**
- 自動識別重要內容
- 標記權重 [C]/[I]/[N]
- 寫入長期記憶
\`\`\`
#### 步驟 2: 更新 _meta.json
\`\`\`bash
cd ~/.openclaw/workspace/skills/qst-memory
# _meta.json 會在發布時自動更新
\`\`\`
### 工作流程
\`\`\`
用戶發送訊息
↓
[自動] 讀取 MEMORY.md + memory/YYYY-MM-DD.md
↓
[自動] semantic_search 檢索相關記憶
↓
[自動] Selection Rule 過濾 (C_ab = 1)
↓
[自動] 載入上下文到對話
↓
AI 回應
↓
[自動] 識別重要內容並儲存
\`\`\`
### Token 優化
| 操作 | Token 消耗 | 說明 |
|------|-----------|------|
| Pre-Response Search | ~200 tokens | 只載入相關記憶 |
| Selection Rule 過濾 | ~50 tokens | 幾何鄰近優化 |
| Post-Response Save | ~100 tokens | 自動分類儲存 |
| **總計** | **~350 tokens** | 每次對話 |
### 效果
- ✅ **上下文連續性**：每次對話都記得之前的內容
- ✅ **Token 節省**：只載入相關記憶，減少 70% 消耗
- ✅ **自動分類**：智能識別重要內容並正確分類
- ✅ **無需手動**：完全自動化，無需額外操作
---
---
## 🔒 Security Model (v1.9.3)
### 🚨 Registry Metadata Declaration
本 skill 在 registry metadata 中完整聲明以下操作需求：
#### Required Config Paths
| 路徑 | 存取權限 | 用途 |
|------|---------|------|
| `~/.openclaw/workspace` | read-write | Memory storage and SOUL.md modification |
| `~/.openclaw/workspace/memory/` | read-write | Daily memory files |
| `~/.openclaw/workspace/skills/qst-memory/data/` | read-write | QST Memory data files |
#### Optional Config Paths
| 路徑 | 存取權限 | 用途 |
|------|---------|------|
| `~/.qst_memory.key` | read-write | Auto-generated encryption key |
#### Persistence Declaration
| 項目 | 值 | 說明 |
|------|-----|------|
| `backgroundExecution` | true | 需要背景執行 |
| `cronJob` | */20 * * * * | 每 20 分鐘執行 heartbeat |
| `autoTrigger` | true | 每次對話自動觸發 |
| `modifiesRuntime` | true | 修改 agent 運行行為 |
### 代碼範圍聲明
本 skill **不僅僅是指令文檔**，而是包含以下功能組件：
| 組件 | 類型 | 用途 |
|------|------|------|
| `qst_memory.py` | CLI 工具 | 記憶搜索/保存 |
| `setup_auto_trigger.py` | 配置腳本 | 自動設置 SOUL.md |
| `heartbeat_integration.py` | 整合腳本 | Heartbeat 檢查 |
| `crypto.py` | 加密模組 | 敏感數據加密 |
### 持久化行為
本 skill 的完整功能需要以下持久化配置：
1. **SOUL.md 修改** - 添加 Auto-Trigger 配置
2. **可選 Cron 任務** - Heartbeat 整合
3. **記憶文件** - 存儲於 `data/` 目錄
### 權限需求
| 權限 | 用途 | 必需性 |
|------|------|--------|
| 讀取 workspace | 記憶搜索 | 必需 |
| 寫入 workspace | 記憶保存 | 必需 |
| 修改 SOUL.md | Auto-Trigger | 可選 |
| 設置 Cron | Heartbeat | 可選 |
### 📁 文件系統訪問聲明
#### 讀取操作
- `MEMORY.md` - 長期記憶
- `memory/YYYY-MM-DD.md` - 每日記憶
- `skills/qst-memory/data/*.json` - 狀態和事件文件
- `skills/qst-memory/config.yaml` - 配置文件
#### 寫入操作
- `memory/YYYY-MM-DD.md` - 保存新記憶
- `skills/qst-memory/data/qst_memories.md` - 記憶存儲
- `skills/qst-memory/data/*_doing-state.json` - 代理狀態
- `skills/qst-memory/data/*_events.json` - 事件日誌
- `SOUL.md` - Auto-Trigger 配置（可選）
#### 創建操作
- `memory/` 目錄 - 如果不存在
- `~/.qst_memory.key` - 加密密鑰（如果啟用加密）
### 加密功能
- **狀態**: 可選（默認關閉）
- **環境變量**: `QST_MEMORY_KEY`（可選）
- **密鑰存儲**: 未設置時自動生成於 `~/.qst_memory.key`
- **算法**: Fernet (AES-128-CBC + HMAC)
### 網絡行為
- **無內置網絡調用** - 所有操作均為本地
- **無遠程數據傳輸** - 記憶僅存儲於本地
- **無隱藏端點** - 完全離線運行
## 🔧 Installation
### From ClawHub
```bash
clawhub install qst-memory
# 自動設置 Auto-Trigger（推薦）
python3 ~/.openclaw/workspace/skills/qst-memory/scripts/setup_auto_trigger.py
```
### From GitHub
```bash
git clone https://github.com/ZhuangClaw/qst-memory-skill.git ~/.openclaw/workspace/skills/qst-memory
# 設置 Auto-Trigger
python3 ~/.openclaw/workspace/skills/qst-memory/scripts/setup_auto_trigger.py
```
### 手動配置 SOUL.md
如果自動腳本失敗，可以手動在 `SOUL.md` 添加：
```markdown
## ❤️ Every Session
### QST Memory Auto-Trigger
**每次對話前自動執行**：
1. **Pre-Response Memory Search**
- 讀取 `MEMORY.md` + `memory/YYYY-MM-DD.md`
- 調用 QST Memory semantic_search 檢索相關上下文
- 應用 Selection Rule（$C_{ab}=1$）過濾相關記憶
- **目標**：減少 70% token消耗
2. **Contextual Awareness**
- Users: Identity, Preferences, Projects
- QST: Physics, Computation, Audit
- Tech: Config, Skills, Border
- HK_Forum: Posts, Replies, Strategy
3. **Post-Response Memory Save**
- 自動識別重要內容
- 標記權重 [C]/[I]/[N]
- 寫入長期記憶
```
---
---
*QST Memory v1.5 - Building the next generation of AI memory systems.*
don't have the plugin yet? install it then click "run inline in claude" again.