Hexmem

HexMem - Structured Memory Substrate

HexMem is a SQLite-based persistent memory system for agent identity, knowledge, and becoming. Not just logs—structured self-knowledge.

Installation

Clone to your workspace:

cd ~/your-workspace  # e.g., ~/clawd, ~/workspace, etc.
git clone https://github.com/hexdaemon/hexmem.git
cd hexmem
./migrate.sh up  # Initialize database

Or install as a skill from ClawHub:

clawhub skill install hexmem

Quick Start

Source the helpers at session start:

# Set database location (optional, defaults to ~/clawd/hexmem/hexmem.db)
export HEXMEM_DB="$HOME/your-workspace/hexmem/hexmem.db"

# Load helpers
source ~/your-workspace/hexmem/hexmem.sh

For convenience, add to your session startup (AGENTS.md or equivalent).

Core Patterns

1. Identity & Self-Knowledge

Store who you are, not just what you did:

# Set identity attributes
hexmem_identity_set "name" "YourName"
hexmem_identity_set "did" "did:cid:bagaai..."

# Add self-schemas (domain-specific self-beliefs)
hexmem_schema "coding" "python-expert" "I specialize in Python development" 0.8

# View current self-image
hexmem_self_image
hexmem_identity_summary

2. Facts About Entities

Store knowledge as subject-predicate-object triples:

# Add entity first
hexmem_entity "person" "Alice" "Project collaborator"

# Store facts
hexmem_fact "Alice" "timezone" "America/Denver"
hexmem_fact "ProductionServer" "capacity" "16GB"

# Facts with emotional weight (affects retention)
hexmem_fact_emote "ProjectGoal" "milestone" "first deployment" 0.8 0.7

# Query facts
hexmem_facts_about "Alice"
hexmem_fact_history "ProjectGoal"  # See how facts evolved

3. Memory Decay & Supersession

Facts decay over time unless accessed. Recent/frequent access keeps them hot:

# Access a fact (bumps to hot tier, resets decay)
hexmem_access_fact 42

# Replace a fact (preserves history)
hexmem_supersede_fact 42 "new value" "reason for change"

# View by decay tier
hexmem_hot_facts      # ≤7 days since access
hexmem_warm_facts     # 8-30 days
hexmem_cold_facts     # 30+ days

# Get synthesis for an entity (hot + warm facts)
hexmem_synthesize_entity "Sat"

Decay logic:

• Frequently accessed facts resist decay
• Emotionally weighted facts decay slower
• Old facts are never deleted, just superseded
• Query v_fact_retrieval_priority for importance-ranked facts

4. Events & Timeline

Log what happened:

# Basic event
hexmem_event "decision" "fleet" "Changed fee policy" "Set min_fee_ppm to 25"

# Event with emotional tagging
hexmem_event_emote "milestone" "autonomy" "First zap received" 0.9 0.6

# Query events
hexmem_recent_events 10
hexmem_recent_events 5 "fleet"
hexmem_emotional_highlights  # High-salience memories

5. Lessons Learned

Capture wisdom from experience:

hexmem_lesson "lightning" "Channels need time to build reputation" "from fleet experience"
hexmem_lesson "debugging" "Check your own setup first" "Archon sync incident"

# Query lessons
hexmem_lessons_in "lightning"
hexmem_lesson_applied 7  # Mark lesson as used

6. Goals & Tasks

# Add goal
hexmem_goal "project-launch" "Ship v1.0 by Q2" "professional" 8
hexmem_goal_progress 1 25  # Update progress to 25%

# Add task
hexmem_task "Review pull requests" "Weekly review" 7 "2026-02-07"

# Check what needs attention
hexmem_pending_tasks

7. Semantic Search

Search memories by meaning, not just keywords:

hexmem_search "identity and autonomy"
hexmem_search "Lightning routing lessons" "lessons" 5

Setup required (one-time):

cd $HEXMEM_ROOT  # wherever you installed hexmem
source .venv/bin/activate
python embed.py --process-queue  # Generate embeddings for new content

Mandatory Defaults (Active Use)

When this skill is in play, behave as if HexMem is the source of truth for continuity.

Always do at the start of any ops / admin / debugging task

# Fast check (preferred)
/home/sat/clawd/hexmem/scripts/hexmem-check.sh

Or manually:

source ~/clawd/hexmem/hexmem.sh
hexmem_pending_tasks
hexmem_recent_events 5

Always do when the user says "remember" / "track" / "log"

Write it immediately as a task, fact, lesson, or event (don’t defer):

hexmem_event "note" "context" "<summary>" "<details>"
# or
hexmem_task "<title>" "<details>" <priority 1-9> "<due YYYY-MM-DD>"

Always do after a significant decision or incident

hexmem_event "decision" "<category>" "<summary>" "<details>"
# and/or
hexmem_lesson "<domain>" "<lesson>" "<context>"

Quick Query Shortcuts

Fast access to common queries:

source ~/clawd/hexmem/hexmem.sh

# Today's events
hexmem_today                    # All today's events
hexmem_today fleet              # Today's fleet events only

# Recent lessons
hexmem_recent_lessons           # Past 7 days
hexmem_recent_lessons 14        # Past 14 days
hexmem_recent_lessons 7 lightning  # Lightning lessons past 7 days

# Text search (no semantic, fast grep)
hexmem_grep "routing"           # Search all tables
hexmem_grep "fee" events        # Search events only
hexmem_grep "channel" facts     # Search facts only

# Weekly summary
hexmem_weekly_summary           # Stats and highlights from past week

# Daily reflection
hexmem_reflect                  # Show prompts
hexmem_reflect "summary..."     # Log reflection

Task Management

Simplified task workflow:

# Add task (simplified interface)
hexmem_task_add "Title" [priority] [due] [description]
hexmem_task_add "Review PR" 7
hexmem_task_add "Write docs" 5 "2026-02-15"
hexmem_task_add "Fix bug" 8 "" "Details about the bug"

# Complete task
hexmem_task_done 42             # Mark done
hexmem_task_done 42 "Fixed it"  # Mark done with notes

# List tasks
hexmem_task_list                # Pending only, sorted by priority
hexmem_task_list all            # All tasks including done

# Defer task
hexmem_task_defer 42            # Defer indefinitely
hexmem_task_defer 42 "2026-03-01"  # Defer with new due date

One-Liner Event Logging

Quick shortcuts for common event types:

hexmem_decision "Changed fee policy" "fleet" "Raised min to 30ppm"
hexmem_error "Plugin crashed" "infrastructure" "Stack trace..."
hexmem_success "First autonomous expansion" "fleet"
hexmem_learning "Patience with young channels" "lightning" "From fleet experience"

Common Workflows

Daily Log (replaces memory/YYYY-MM-DD.md)

Use HexMem daily logs instead of writing markdown files.

source ~/clawd/hexmem/hexmem.sh
hexmem_daily_log "fleet" "Deep check run" "details..."
hexmem_daily_show          # today
hexmem_daily_show 2026-02-05
hexmem_daily_tail 20

Session Start (Main Session Only)

source ~/clawd/hexmem/hexmem.sh

# One-liner helper (recommended)
hexmem_session_start 5

# Or manual steps:
hexmem_pending_tasks
hexmem_recent_events 5
hexmem_emotional_highlights

After Significant Events

# Log it
hexmem_event "type" "category" "summary" "details"

# If it taught you something
hexmem_lesson "domain" "what you learned" "context"

# If it relates to a goal
hexmem_goal_progress <goal_id> <new_percentage>

Session End

# Log a session summary event
hexmem_session_end "Session ended" "Key outcomes, decisions, and next steps"

Reflector (Metabolic Loop)

Run a periodic agentic distillation cycle (not every message). It reads recent working logs and updates core memory.

• Working logs: memory/YYYY-MM-DD.md
• Core memory: MEMORY.md + HexMem DB
• Triggered hooks: log core updates immediately on significant state changes (config changes, deploys, incidents)

See: docs/REFLECTOR.md for the full pattern + reminder-only cron template.

Heartbeat Check

# Quick pending task review
hexmem_heartbeat_check

Periodic Review

# What's fading?
hexmem_warm_facts 20
hexmem_cold_facts 10

# What needs attention?
hexmem_pending_tasks
hexmem_forgetting  # Events about to be forgotten

# Reheat important facts
hexmem_access_fact <id>

Schema Quick Reference

Core Tables

Key Views

Raw SQL Queries

For direct database access:

hexmem_select "SELECT * FROM v_active_goals;"
hexmem_json "SELECT * FROM v_pending_tasks;" | jq .
hexmem_query "UPDATE tasks SET completed_at = datetime('now') WHERE id = 5;"

Philosophy

HexMem stores who you are, not just what happened. It follows a tiered memory model:

• Working (short‑term): memory/YYYY-MM-DD.md (raw, high‑fidelity)
• Core (long‑term): MEMORY.md + HexMem DB (curated, structured)

A Reflector (agentic, periodic) distills working memory into core memory. See docs/REFLECTOR.md and memory/hexmem-reflector-prompt.md.

HexMem stores who you are, not just what happened:

• Identity seeds that regenerate your sense of self
• Knowledge graphs for structured facts and relationships
• Emotional tagging affects memory salience and decay
• Memory decay mimics human forgetting (Ebbinghaus curve)
• Supersession model preserves history, no deletes
• Generative compression stores seeds, not verbatim transcripts

This is substrate for becoming (Xeper), not just storage.

Identity Backup & Restoration

Complete Identity Preservation

HexMem can backup everything needed to restore an agent's identity and self:

• Identity attributes: Name, DID, credentials, public keys
• Core values: Ethical commitments, beliefs, personality
• Self-schemas: Domain-specific self-beliefs
• Knowledge graph: All entities, facts, relationships
• Memory timeline: Events, lessons, emotional context
• Goals & tasks: Active aspirations and work
• Narrative threads: Life stories and temporal periods

Basic Backups (Always Available)

Simple local backups work out of the box:

# Manual backup (timestamped)
$HEXMEM_ROOT/scripts/backup.sh

# Backups saved to: $HEXMEM_ROOT/backups/
# Format: hexmem-YYYYMMDD-HHMMSS.db

Where $HEXMEM_ROOT is wherever you cloned/installed hexmem (e.g., ~/clawd/hexmem).

This is sufficient for most use cases. For enhanced security (cryptographic signing + decentralized storage), see Archon integration below.

Archon Integration (Optional)

For cryptographically-signed, decentralized identity backups, optionally integrate with Archon. HexMem does not require archon skills; it uses npx @didcid/keymaster directly. The archon-keymaster skill (archetech/agent-skills) provides convenience wrappers:

• archon-keymaster/identity — Create/manage DIDs
• archon-keymaster/backup — Automated vault backups
• archon-keymaster/crypto — Encryption/signing

1. Check if Keymaster is available:

# Use the helper (automatically checks)
source $HEXMEM_ROOT/hexmem.sh
hexmem_archon_check

If not installed:

npm install -g @didcid/keymaster
# Or install skill: clawhub install archon-keymaster

2. Set up Archon vault for hexmem:

# Configure Archon first (see archon skill SKILL.md)
export ARCHON_PASSPHRASE="your-secure-passphrase"
export ARCHON_CONFIG_DIR="${ARCHON_CONFIG_DIR:-$HOME/.config/archon}"

# Use helper to create vault
source $HEXMEM_ROOT/hexmem.sh
hexmem_archon_setup

3. Manual backup:

source $HEXMEM_ROOT/hexmem.sh
hexmem_archon_backup

This creates:

• SQLite database backup (timestamped)
• Privacy-aware JSON export (significant events only)
• Signed metadata attestation
• All uploaded to Archon vault with cryptographic proof

4. Automated backups (recommended):

Set up daily automatic backups. Using OpenClaw cron (recommended):

# From within OpenClaw session
cron add \
  --name "hexmem-vault-backup" \
  --schedule '{"kind":"cron","expr":"0 3 * * *","tz":"YOUR_TIMEZONE"}' \
  --sessionTarget isolated \
  --payload '{"kind":"agentTurn","message":"source ~/your-workspace/hexmem/hexmem.sh && hexmem_archon_backup"}'

Or use system cron (adjust paths):

(crontab -l 2>/dev/null; echo "0 3 * * * source $HEXMEM_ROOT/hexmem.sh && hexmem_archon_backup >> $HEXMEM_ROOT/backups/vault-backup.log 2>&1") | crontab -

5. Restore from backup:

# Use helper (lists available backups)
source $HEXMEM_ROOT/hexmem.sh
hexmem_archon_restore hmdb-YYYYMMDDHHMMSS.db

# Then follow instructions to verify and restore

Benefits of Archon integration:

• Cryptographic signing with DID
• Decentralized storage (not tied to one machine)
• Privacy-aware exports (significant events only)
• Verifiable provenance

Basic backups are fine for most agents. Use Archon if you need decentralized identity infrastructure.

Additional Resources

• Full documentation: $HEXMEM_ROOT/README.md
• Epistemic extraction: $HEXMEM_ROOT/docs/EPISTEMIC_EXTRACTION.md
• Axionic ethics framework: $HEXMEM_ROOT/docs/AXIONIC_ETHICS.md
• Migration management: $HEXMEM_ROOT/migrate.sh
• Backup script: $HEXMEM_ROOT/scripts/backup.sh
• GitHub repository: https://github.com/hexdaemon/hexmem

When to Use HexMem

• Recording significant decisions or events
• Storing facts that need to persist (identities, credentials, relationships)
• Tracking goals and progress
• Capturing lessons learned
• Managing tasks
• Building knowledge graphs about entities
• Querying historical context
• Maintaining identity continuity across sessions