VectorClaw

Provides a secure, least-privilege interface for managing user data, personas, and config snapshots in MySQL with input validation and secret redaction.

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. v3.0.0 replaces the local MySQL dependency with MyVector (MySQL 8.4 + vector search) running in a Docker container. All SQL is routed through docker exec into the MyVector container. Requires a dedicated least-privilege MySQL user — root/admin accounts are rejected.

Version

3.0.0 – 2026-05-11

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

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

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 Types (mem0-like)

Type	Table	Description	Example
Episodic	user_context	Specific events/experiences with timestamps	"User mentioned their dog died last week"
Semantic	user_context	General facts and knowledge	"User is a software developer"
Procedural	user_context	How-to knowledge and habits	"User prefers concise responses"
Emotional	user_mood	Emotional states with triggers and intensity	"User was stressed about deadline"
Preference	user_preferences	Explicit preferences with confidence	"User likes dark mode"
Synaptic	synaptic_memory	Key-value memory with priority and decay	Quick-access facts with auto-decay

Security

• MyVector Docker container: All SQL runs inside the container via docker exec. No local MySQL installation required.
• Dedicated least-privilege user required: root/admin accounts are explicitly rejected. The skill fails closed if credentials are missing.
• Password never on command line: Uses temporary --defaults-extra-file with chmod 600, cleaned up via trap on any exit.
• .env parsed safely: KEY=VALUE line parsing only — never evaluated as shell code.
• query command is SELECT-only (no DML through query)
• DML (INSERT/UPDATE/DELETE/REPLACE) requires interactive user confirmation
• Single-statement execution only (semicolons rejected)
• DDL blocked (DROP, TRUNCATE, CREATE, ALTER, GRANT, REVOKE)
• Table allowlist enforced for all write operations (26 approved tables)
• Path traversal and sensitive file patterns blocked
• Comment injection blocked (/* */, --, # style comments rejected)
• Hex-encoded string detection blocked (prevents 0x... bypasses)
• Proper MySQL string escaping via Python (handles all edge cases)
• Enum validation on all convenience command parameters (no arbitrary strings)
• Foreign key constraints prevent orphaned data
• Script permissions: 700 (owner execute only)
• Config directory permissions: 700

Data Retention & Deletion

Retention Policies (enforced)

• user_interactions: 30-day rolling window — older entries should be archived or purged
• user_mood: 90-day rolling window — emotional data ages quickly
• thought_stream: 30-day rolling window
• synaptic_memory: auto-decay via decay_rate column — low-priority entries fade naturally
• 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

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
• No backups of user data outside the mysqlclaw database

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

Sentiment Scoring

Sentiment is tracked at multiple levels:

• 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)

Engagement Patterns

Automatically tracked 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, allowed_snapshot_paths table, and related commands were removed to prevent storage of sensitive operational files.
• Local MySQL dependency removed (v3.0.0): Replaced with MyVector Docker container. No local MySQL server or client required.

Change Log

See changelog.md for full version history.

Setup Guide

For step-by-step instructions on setting up MyVector, creating the database with proper security, and applying the schema, see SETUP_GUIDE.md.

Visit https://clawhub.ai/paradoxfuzzle/custom-mysql for live updates.