Soul Memory

Intelligent memory management system v3.6.1 - reliable pre-response memory injection for OpenClaw with pure JSON CLI output, last-user-message query extracti...

Security Scan

The skill appears to be a legitimate OpenClaw memory plugin, but there are inconsistencies and operational behaviors (install script, cron/heartbeat automation, hard-coded root/workspace paths, and a bundled web UI) that merit careful review before installing or enabling it.

Purpose & Capability

The name/description (long-term memory for OpenClaw) match the included code (core, vector search, semantic cache, OpenClaw plugin manifest, CLI, heartbeat scripts, web UI). However the skill metadata claims no required config paths or env vars while the SKILL.md and scripts explicitly reference and modify ~/.openclaw/openclaw.json, install into ~/.openclaw/extensions, and read/write /root/.openclaw/workspace/memory — an inconsistency worth noting.

Instruction Scope

Runtime instructions ask you to git clone and run install.sh, edit ~/.openclaw/openclaw.json, restart the OpenClaw gateway, and rely on heartbeat and post-response auto-save flows that read and persist conversation data (daily Markdown backups and JSON indices). Those actions are within a memory plugin's scope, but they also grant the skill broad local file access and automatic periodic execution (cron/heartbeat). The SKILL.md/HEARTBEAT.md show scripts that read and rewrite user's memory files (including hard-coded /root paths) and could modify or remove content via cleanup scripts — review before allowing automatic runs.

Install Mechanism

There is no registry 'install' spec in the metadata, but SKILL.md instructs cloning from GitHub and running the bundled install.sh. The repository includes install.sh, uninstall.sh, and scripts that likely register cron jobs or integrate with OpenClaw. Running a non-reviewed shell installer from a third-party repo is higher-risk; you should inspect install.sh and understand what it will change (cron, file system locations, service restarts) before executing it.

Credentials

The skill declares no required environment variables or secrets, which matches the lack of explicit cloud API keys in SKILL.md. That said, the code claims Git integration/version control and includes a web UI; these features could prompt credential use (git push, exposing a web endpoint) even though no creds are declared — verify whether the code ever attempts network auth or remote uploads.

Persistence & Privilege

always:false (not force-included) and autonomous invocation is allowed (normal). However the skill's files and docs indicate it will persist conversation data to disk (cache/index.json, memory/YYYY-MM-DD.md), run heartbeat/cleanup on a schedule, and potentially start a local web dashboard. Those are substantial persistent behaviors and can modify user data or expose it if the web UI is misconfigured—inspect install actions that create cron jobs, services, or open network ports.

What to consider before installing

This package is plausibly a real OpenClaw memory plugin, but treat it like any untrusted code: 1) Review install.sh and uninstall.sh before running—look for cron edits, file writes, system service changes, or network calls. 2) Inspect web/app.py and any code that starts servers to ensure it doesn't bind publicly or send data externally. 3) Check heartbeat/clean_heartbeat scripts to confirm what files they modify and whether paths are hard-coded (they reference /root/.openclaw/...). 4) Back up ~/.openclaw/openclaw.json and your memory folder before installing and consider testing inside an isolated container or VM. 5) If you need to enable automatic cron/heartbeat behaviors, restrict them to a least-privilege account (not root) and verify logs for unexpected activity. 6) If you are not comfortable auditing the code yourself, ask a developer to search for outbound network calls, hard-coded endpoints, or credential usage within the repo prior to installation.

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

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