SQL Memory Skill#

Semantic memory layer for OpenClaw agents

Overview#

Provides agent-friendly memory operations: remember, recall, search, forget, plus task queue management, knowledge indexing, activity logging, and hierarchical memory rollups. All operations go through the SQL Connector skill for reliable, parameterized SQL execution.

See scripts/sql_memory.py for full implementation.

Dependencies#

• sql-connector — provides the underlying database connection and query execution

Quick Start#

python

from sql_memory import SQLMemory, get_memory

mem = get_memory('cloud')

# Remember something
mem.remember('facts', 'vex_timezone', 'VeX is in EST/EDT timezone', importance=7)

# Recall it
entry = mem.recall('facts', 'vex_timezone')

# Search across all memories
results = mem.search_memories('timezone')

# Queue a task
mem.queue_task('nlp_agent', 'analyze_document', '{"doc": "..."}', priority=3)

# Log an event
mem.log_event('training_complete', 'nlp_agent', 'Finished training cycle 42')

# Store knowledge
mem.store_knowledge('stamps', 'inverted_jenny', 'Rare 1918 misprint...', 'catalog')

Schema#

All tables live in the memory schema (SQL Server database):

TablePurposememory.MemoriesLong-term curated memories with importance scoringmemory.TaskQueueTask queue for agent work itemsmemory.ActivityLogEvent/activity logging for audit trailmemory.KnowledgeIndexDomain-specific knowledge storememory.SessionsSession tracking for agents

Memory Rollups#

Hierarchical consolidation keeps memories fresh and relevant:

text

Daily memories → Weekly rollup (Sundays 3AM)
Weekly rollups → Monthly rollup (1st of month)
Monthly → Quarterly (Jan/Apr/Jul/Oct)
Quarterly → Yearly (Jan 1st)

Each rollup:

1. Summarizes source entries
2. Creates a consolidated entry with back-references
3. Reduces importance of source entries
4. Tags sources as rolled_up

Importance Scale#

LevelMeaningExample1-2Ephemeral, archiveOld workspace file3-4Context, nice-to-knowDebug notes5-6Standard operationalTask completion7-8Important milestoneArchitecture decision9CriticalSystem design choice10PermanentCore identity/values

API Reference#

Memory Operations#

MethodDescriptionExampleremember(cat, key, content, importance, tags)Store a memorymem.remember('facts', 'name', 'Oblio', 7)``recall(cat, key)Retrieve a memorymem.recall('facts', 'name')``search_memories(query, limit)Semantic searchmem.search_memories('timezone', limit=5)``forget(cat, key)Delete a memorymem.forget('facts', 'name')

Task Queue#

MethodDescriptionqueue_task(agent, type, payload, priority)Add a taskclaim_task(id)Mark task as processingcomplete_task(id, result)Mark task as completedfail_task(id, error, retries, max)Fail with retry logic

Activity Logging#

MethodDescriptionlog_event(type, agent, detail, extra)Log an activityget_recent_activity(hours, agent)Query recent events

Configuration#

Uses the same environment variables as sql-connector:

text

SQL_CLOUD_SERVER=sql5112.site4now.net
SQL_CLOUD_DATABASE=db_99ba1f_memory4oblio
SQL_CLOUD_USER=...
SQL_CLOUD_PASSWORD=...

SQL_LOCAL_SERVER=10.0.0.110
SQL_LOCAL_DATABASE=Oblio_Memories
SQL_LOCAL_USER=sa
SQL_LOCAL_PASSWORD=...

Architecture#

text

┌──────────────────┐
│   Agents         │ ← OblioAgent subclasses
├──────────────────┤
│   SQLMemory      │ ← Semantic operations (remember/recall/queue/log)
├──────────────────┤
│   SQLConnector   │ ← Generic SQL execution (retry, parameterized, logging)
├──────────────────┤
│   pymssql (TDS)  │ ← Native SQL Server driver
└──────────────────┘

License#

MIT