Soul Memory

Soul Memory System v3.6.1

🧠 Intelligent Memory Management System

Long-term memory framework for AI agents with full OpenClaw integration. v3.6.1 修正 pre-response memory injection 主流程：CLI 純 JSON 輸出、優先使用最後一條 user message 作 query、分類記憶注入（User / QST / Config / Recent / Project / General）、重點摘要壓縮、以及命中審計日誌。

✨ Features

8 Powerful Modules + OpenClaw Plugin Integration

🆕 v3.3.1 Release Highlights

🎯 Heartbeat 自動清理（最新！）

v3.2.2 Release Highlights

🎯 Core Improvements

🔄 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