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

| Type | Table | Description | |------|-------|-------------| | Episodic | user_context | Specific events/experiences with timestamps | | Semantic | user_context | General facts and knowledge | | Procedural | user_context | How-to knowledge and habits | | Emotional | user_mood | Emotional states with triggers and intensity | | Preference | user_preferences | Explicit preferences with confidence | | Synaptic | synaptic_memory | Key-value memory with priority and decay | | HoloGraphic | user_context (metadata) | Multi-dimensional tags (emotion, context, urgency, people) | | Hancho | user_context (reasoning) | Derived knowledge graph relationships | | HindSight | user_context (discovery) | Post-conversation consolidation findings |

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:

python3 memory_consolidation.py --user <discord_id>
python3 memory_consolidation.py --all-users
python3 memory_consolidation.py --user <id> --dry-run
python3 memory_consolidation.py --user <id> --hindisght-only
python3 memory_consolidation.py --user <id> --holohraphic-only
python3 memory_consolidation.py --user <id> --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

| Option | Default | Notes | |-----------------|---------------|----------------------------------------| | MYSQL_USER | required | Dedicated least-privilege account (NOT root) | | MYSQL_PASSWORD| required | Store in .env (chmod 600) | | MYSQL_PORT | 3310 | MyVector Docker port mapping | | DATABASE | mysqlclaw | Target database |

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 https://clawhub.ai/paradoxfuzzle/custom-mysql for live updates.