paradoxfuzzle/custom-mysql

Overview

Security-hardened MyVector MySQL profile storage with capability bounding for OpenClaw. Tracks interactions, relationships, context, skill usage, notes, preferences, media, food, personas, mood states, engagement patterns, proactive reminders, agent learnings, community sentiment, trending topics, and community events. Now includes HindSight (post-conversation consolidation), HoloGraphic (multi-dimensional tagging), and Hancho (knowledge graph reasoning) memory systems. v4.0.0 integrates with the memory_consolidation.py script for automated heartbeat-based memory maintenance. All SQL is routed through docker exec into the MyVector container. Requires a dedicated least-privilege MySQL user — root/admin accounts are rejected.

Version

4.0.0 – 2026-05-21

Memory Systems

VectorClaw v4.0.0 includes three memory enhancement systems:

HindSight — Post-Conversation Consolidation

• Analyzes recent interactions (sentiment trends, topic frequency)
• Identifies new topics not yet stored as memories
• Detects recurring themes worth tracking
• Stores findings in user_context (categories: discovery, behavioral, emotional)

HoloGraphic — Multi-Dimensional Tagging

• Tags memories with: emotion, context, urgency, people
• Emotion: positive, negative, complex, neutral
• Context: work, personal, health, tech, social, creative
• Urgency: immediate, ongoing, timeless, historical
• People: auto-detected names (NoodlyPanda, Ev, Cyle, Jerith, etc.)
• Enables retrieval from any angle ("how did Ev feel about X", "health topics in May")
• Stores tags in user_context (category: metadata)

Hancho — Knowledge Graph Reasoning

• Connects related facts to derive new insights via 7 reasoning rules:

1. medication_side_effects: medication keywords + side effect keywords
2. health_chain: condition keywords + treatment keywords
3. tech_infrastructure: infra keywords + AI/model keywords
4. creative_passion: interest keywords + creation keywords
5. relationship_depth: emotional keywords + interaction keywords
6. interest_to_skill: learning keywords + skill keywords
7. emotional_pattern: stress keywords + coping keywords
• Inter-user reasoning finds shared topics between users
• Stores derived insights in user_context (categories: reasoning, social_graph)

Memory Types

Consolidation Script

• memory_consolidation.py at ~/.openclaw/workspace/scripts/memory_consolidation.py
• Runs HindSight + HoloGraphic + Hancho in sequence
• Scheduled every 6 hours via heartbeat and cron
• Commands:

```bash

python3 memory_consolidation.py --user

python3 memory_consolidation.py --all-users

python3 memory_consolidation.py --user --dry-run

python3 memory_consolidation.py --user --hindisght-only

python3 memory_consolidation.py --user --holohraphic-only

python3 memory_consolidation.py --user --hancho-only

```

Capabilities

• MyVector MySQL read/write operations only (no external APIs, crypto, or wallets)
• All SQL routed through MyVector Docker container via docker exec
• Uses .env files for credentials (parsed as KEY=VALUE, never shell-sourced)
• All SQL routed through sql_safe_exec.sh for safety
• query command is SELECT-only
• DML requires interactive confirmation (no non-interactive bypass)
• Table allowlist enforced for all write operations (26 approved tables)
• Single-statement execution only (semicolons rejected)
• DDL blocked (DROP, TRUNCATE, CREATE, ALTER, GRANT, REVOKE)
• Comment injection blocked (/ /, --, #)
• Hex-encoded string detection blocked
• Path traversal and sensitive file patterns blocked
• Proper MySQL string escaping via Python (handles all edge cases)
• Enum validation on all convenience command parameters
• FAIL CLOSED: refuses to connect if MYSQL_USER or MYSQL_PASSWORD is missing
• REJECTS root/admin users: requires dedicated least-privilege account
• Verifies MyVector container is running before attempting connection
• Memory consolidation: HindSight + HoloGraphic + Hancho reasoning via heartbeat

Configuration

MyVector Docker container must be running:

docker run -d --name myvector-db -p 3310:3306 \
  -e MYSQL_ROOT_PASSWORD=<root_pw> \
  -e MYSQL_DATABASE=mysqlclaw \
  ghcr.io/askdba/myvector:mysql8.4

Installation

# 1. Start MyVector container (if not running)
docker run -d --name myvector-db -p 3310:3306 \
  -e MYSQL_ROOT_PASSWORD=<root_pw> \
  -e MYSQL_DATABASE=mysqlclaw \
  ghcr.io/askdba/myvector:mysql8.4

# 2. Create a dedicated least-privilege user inside MyVector
docker exec -it myvector-db mysql -u root -p<root_pw> -e "
  CREATE USER IF NOT EXISTS 'mysqlclaw'@'%' IDENTIFIED BY '<strong_password>';
  GRANT SELECT, INSERT, UPDATE, DELETE ON mysqlclaw.* TO 'mysqlclaw'@'%';
  FLUSH PRIVILEGES;
"

# 3. Create .env file with the dedicated user's credentials
cat > .env <<'EOF'
MYSQL_USER=mysqlclaw
MYSQL_PASSWORD=<strong_password>
MYSQL_PORT=3310
DATABASE=mysqlclaw
EOF
chmod 600 .env

# 4. Apply schema with setup wizard
cd ~/.openclaw/workspace/skills/custom-mysql
./setup_wizard.sh

# 5. Run initial consolidation
cd ~/.openclaw/workspace
python3 scripts/memory_consolidation.py --user <your_discord_id>

Usage

# Query (SELECT-only)
custom_mysql.sh query "SELECT * FROM users LIMIT 5"

# Execute script (DML requires interactive confirmation)
custom_mysql.sh exec --file /path/to/scripts.sql

# Convenience commands:
custom_mysql.sh insert_interaction <uid> <dir> <topic> <summary> [sentiment] [is_important]
custom_mysql.sh insert_note <uid> <note> [category] [is_pinned]
custom_mysql.sh insert_context <uid> <key> <value> [type] [importance] [expires_at]
custom_mysql.sh insert_skill_usage <uid> <skill_name> [action] [status] [duration_ms] [error_type]
custom_mysql.sh insert_relationship <uid> <related_uid> <type> [strength] [trust] [notes]
custom_mysql.sh insert_mood <uid> <mood> [intensity] [trigger_topic] [confidence]
custom_mysql.sh insert_reminder <uid> <trigger_type> <condition> <text> [priority]
custom_mysql.sh insert_thought <uid> <thought> [type] [channel_id]
custom_mysql.sh insert_learning <type> <title> <description> [priority] [user] [skill]
custom_mysql.sh insert_event <type> <title> [description] [channel_id]

# Memory consolidation (v4.0.0):
python3 ~/.openclaw/workspace/scripts/memory_consolidation.py --user <uid>
python3 ~/.openclaw/workspace/scripts/memory_consolidation.py --all-users

Data Retention & Deletion

Retention Policies

• user_interactions: 30-day rolling window
• user_mood: 90-day rolling window
• user_context (HoloGraphic metadata): 30-day refresh cycle
• user_context (Hancho reasoning): 90-day review cycle
• user_context (HindSight discoveries): 90-day review cycle
• thought_stream: 30-day rolling window
• synaptic_memory: auto-decay via decay_rate column
• community_sentiment, trending_topics: 90-day rolling window
• user_activity_heatmap: rolling 90-day windows
• user_notes, user_relationships, skill_usage, user_context: retained until explicitly deleted
• proactive_reminders: auto-deactivate after max_triggers reached
• memory_consolidation_log: retained for auditing (no auto-delete)

Deletion

• Full user data deletion via rollback_user.sql covers all 26 user-data tables
• Rollback procedure wipes all user-specific data while preserving schema

Consent & Provenance

• All profile data is stored only for the user who provided it
• Inferred data must be marked with source: 'inferred' and lower confidence
• Emotional/mood data requires confidence ≥ 0.7
• agent_learnings and rule-like memories must be reviewed before affecting future behavior
• Explicit opt-in required for each data source

Security

• MyVector Docker container: All SQL runs inside the container via docker exec
• Dedicated least-privilege user required: root/admin accounts explicitly rejected
• Password never on command line: Uses temporary --defaults-extra-file with chmod 600
• .env parsed safely: KEY=VALUE line parsing only — never evaluated as shell code
• query command is SELECT-only (no DML through query)
• DML requires interactive user confirmation
• Single-statement execution only (semicolons rejected)
• DDL blocked (DROP, TRUNCATE, CREATE, ALTER, GRANT, REVOKE)
• Table allowlist enforced (26 approved tables)
• Path traversal and sensitive file patterns blocked
• Comment injection blocked
• Hex-encoded string detection blocked
• Proper MySQL string escaping via Python
• Foreign key constraints prevent orphaned data
• Script permissions: 700 (owner execute only)
• Config directory permissions: 700

Sentiment Scoring

• Per interaction: user_interactions.sentiment (enum) + sentiment_score (float, -1 to 1)
• Per user trend: Rolling average from recent interactions
• Community-wide: community_sentiment aggregated by time period
• Mood impact: Each interaction can shift user's mood (mood_impact field)
• HindSight analysis: Automated sentiment trend analysis during consolidation

Engagement Patterns

• Time of day: When user is most active
• Day of week: Weekly activity cycles
• Topic triggers: What topics engage this user most
• Channel preference: Which channels they use
• Response style: How they prefer to interact
• Session length: Typical interaction duration
• Activity bursts: Periods of high activity

Removed Features

• Snapshot functionality removed (v1.1.7): The agent_config_files` table and related commands removed
• Local MySQL dependency removed (v3.0.0)`: Replaced with MyVector Docker container

Change Log

See changelog.md for full version history.

Setup Guide

For step-by-step instructions, see SETUP_GUIDE.md.

Visit for live updates.