Soul Memory System v3.5.7

🧠 Intelligent Memory Management System

Long-term memory framework for AI agents with full OpenClaw integration. v3.5.7 修復 get_active_session_id() 排除 cron session，避免誤選 HEARTBEAT session；v3.5.6 放寬 normalize_for_dedup() 保留時間戳差異；v3.5.5 提高 threshold 到 0.92 減少誤去重；v3.5.4 放寬 stable_cues 保存更多技術/項目/QST/文件內容。

---

✨ Features

8 Powerful Modules + OpenClaw Plugin Integration

Module	Function	Description
A	Priority Parser	[C]/[I]/[N] tag parsing + semantic auto-detection
B	Vector Search	Keyword indexing + CJK segmentation + semantic expansion
C	Dynamic Classifier	Auto-learn categories from memory
D	Version Control	Git integration + version rollback
E	Memory Decay	Time-based decay + cleanup suggestions
F	Auto-Trigger	Pre-response search + Post-response auto-save
G	Cantonese Branch	🆕 語氣詞分級 + 語境映射 + 粵語檢測
H	CLI Interface	🆕 Pure JSON output for external integration
Plugin	OpenClaw Hook	🆕 before_prompt_build Hook for automatic context injection
Web	Web UI	FastAPI dashboard with real-time stats

---

🆕 v3.3.1 Release Highlights

🎯 Heartbeat 自動清理（最新！）

Feature	Description
Auto Cleanup Script	Automatically cleans Heartbeat reports every 3 hours
Cron Job Integration	OpenClaw Cron system scheduled execution
Multi-format Support	Recognizes multiple Heartbeat formats
Memory Optimization	Reduces redundancy, improves quality score (7.9 → 8.5)

v3.2.2 Release Highlights

🎯 Core Improvements

Feature	Description
Heartbeat Deduplication	MD5 hash tracking, automatically skips duplicate content
CLI Interface	Pure JSON output for external system integration
OpenClaw Plugin	Automatically injects relevant memories before responses (v0.2.1-beta)
Lenient Mode	Lower recognition thresholds, saves more conversation content

🔄 Plugin v0.2.1-beta Fixes

• Fix prependContext Accumulation: Extracts query from event.prompt instead of messages history
• Enhanced Legacy Cleanup: Multiple format support (SoulM markers, numbered entries, ## Memory Context)
• No Memory Loop: Prevents recursive injection in conversation history

---

🚀 Quick Start

Installation

# Clone and install
git clone https://github.com/kingofqin2026/Soul-Memory-.git
cd Soul-Memory-
bash install.sh

# Clean install (uninstall first if needed)
bash install.sh --clean

Basic Usage

from soul_memory.core import SoulMemorySystem

# Initialize system
system = SoulMemorySystem()
system.initialize()

# Search memories
results = system.search("user preferences", top_k=5)

# Add memory
memory_id = system.add_memory("[C] User likes dark mode")

# Pre-response trigger (auto-search before answering)
context = system.pre_response_trigger("What are user preferences?")

CLI Usage

# Pure JSON output
python3 cli.py search "QST physics" --format json

# Get stats
python3 cli.py stats --format json

OpenClaw Plugin

# Plugin is automatically installed to ~/.openclaw/extensions/soul-memory

# Restart Gateway to enable
openclaw gateway restart

v3.6.1 Highlights

• Pure JSON CLI output for reliable plugin parsing
• Prefer last real user message over prompt tail for memory search query
• Distilled memory summaries instead of raw long snippets
• Typed memory focus buckets: User / QST / Config / Recent / Project / General
• Audit logs for query source and injection buckets

---

🤖 OpenClaw Plugin Integration

How It Works

Automatic Trigger: Executes before each response

1. Extract query from the last real user message (prompt only as fallback)
2. Search relevant memories (top_k = 5)
3. Group and distill memory focus
4. Inject into prompt via prependContext

Configuration

Edit ~/.openclaw/openclaw.json:

{
  "plugins": {
    "entries": {
      "soul-memory": {
        "enabled": true,
        "config": {
          "topK": 5,
          "minScore": 0.0
        }
      }
    }
  }
}

---

🧪 Testing

# Run full test suite
python3 test_all_modules.py

# Expected output:
# 📊 Results: 8 passed, 0 failed
# ✅ All tests passed!

---

📋 Feature Details

Priority System

• [C] Critical: Key information, must remember
• [I] Important: Important items, needs attention
• [N] Normal: Daily chat, can decay

Keyword Search

Localized implementation:

• Keyword indexing
• Synonym expansion
• Similarity scoring

Classification System

Default categories (customizable):

• User_Identity（用戶身份）
• Tech_Config（技術配置）
• Project（專案）
• Science（科學）
• History（歷史）
• General（一般）

Cantonese Support

• 語氣詞分級（唔好、好啦、得咩）
• 語境映射（褒貶情緒識別）
• 粵語檢測（簡繁轉換支持）

---

📦 File Structure

soul-memory/
├── core.py              # Core system
├── cli.py               # CLI interface
├── install.sh           # Auto-install script
├── uninstall.sh         # Complete uninstall script
├── test_all_modules.py  # Test suite
├── SKILL.md             # ClawHub manifest (this file)
├── README.md            # Documentation
├── modules/             # 6 functional modules
│   ├── priority_parser.py
│   ├── vector_search.py
│   ├── dynamic_classifier.py
│   ├── version_control.py
│   ├── memory_decay.py
│   └── auto_trigger.py
├── plugin/              # OpenClaw Plugin
│   ├── index.ts         # Plugin source
│   └── openclaw.plugin.json
├── cache/               # Cache directory (auto-generated)
└── web/                 # Web UI (optional)

---

🔒 Uninstallation

Complete removal of all integration configs:

# Basic uninstall (will prompt for confirmation)
bash uninstall.sh

# Create backup before uninstall (recommended)
bash uninstall.sh --backup

# Auto-confirm (no manual confirmation)
bash uninstall.sh --backup --confirm

Removed Items:

1. OpenClaw Plugin config (~/.openclaw/openclaw.json)
2. Heartbeat auto-trigger (HEARTBEAT.md)
3. Auto memory injection (Plugin)
4. Auto memory save (Post-Response Auto-Save)

---

🔒 Privacy & Security

• ✅ No external API calls
• ✅ No cloud dependencies
• ✅ Cross-domain isolation, no data sharing
• ✅ Open source MIT License
• ✅ CJK support (Chinese, Japanese, Korean)

---

📐 Technical Details

• Python Version: 3.7+
• Dependencies: None external (pure Python standard library)
• Storage: Local JSON files
• Search: Keyword matching + semantic expansion
• Classification: Dynamic learning + preset rules
• OpenClaw: Plugin v0.2.1-beta (TypeScript)

---

📝 Version History

• v3.3.4 (2026-03-07): 🆕 查詢過濾優化（跳過問候語/簡單命令，提高搜索閾值 minScore 0.0→3.0，節省 ~25k token/日）
• v3.3.3 (2026-03-06): 每日快取自動重建（跨日索引更新）
• v3.3.2 (2026-02-28): Heartbeat 自我報告過濾
• v3.3.1 (2026-02-27): 🆕 Heartbeat 自動清理 + Cron Job 集成 + 記憶質量優化（7.9→8.5）
• v3.2.2 (2026-02-25): Heartbeat deduplication + OpenClaw Plugin v0.2.1-beta + Uninstall script
• v3.2.1 (2026-02-19): Index strategy improvement - 93% Token reduction
• v3.2.0 (2026-02-19): Heartbeat active extraction + Lenient mode
• v3.1.1 (2026-02-19): Hotfix: Dual-track memory persistence
• v3.1.0 (2026-02-18): Cantonese grammar branch: Particle grading + context mapping
• v3.0.0 (2026-02-18): Web UI v1.0: FastAPI dashboard + real-time stats
• v2.2.0 (2026-02-18): CJK smart segmentation + Post-Response Auto-Save
• v2.1.0 (2026-02-17): Rebrand to Soul Memory, technical neutralization
• v2.0.0 (2026-02-17): Self-hosted version

---

📄 License

MIT License - see LICENSE for details

---

🙏 Acknowledgments

Soul Memory System v3.2 is a personal AI assistant memory management tool, designed for personal use. Not affiliated with OpenClaw project.

---

🔗 Related Links

• GitHub: https://github.com/kingofqin2026/Soul-Memory-
• Documentation: https://github.com/kingofqin2026/Soul-Memory-/blob/main/README.md
• Web: https://qsttheory.com/

---

© 2026 Soul Memory System