| name | sql-memory |
| version | 2.1.0-alpha |
| status | alpha |
| description | Semantic memory layer for OpenClaw agents. Use when: (1) persisting agent memories with importance scoring, (2) hierarchical memory rollups (daily→weekly→monthly→yearly), (3) queuing tasks for agents, (4) logging activity and audit trails, (5) managing knowledge bases with semantic search. Provides remember/recall/search/queue_task/log_event/add_todo APIs. Built on sql-connector. Requires SQL Server schema setup — see README. ALPHA: use at your own risk, API may change. |
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 sql_memory.py for full implementation.
Dependencies
- sql-connector — provides the underlying database connection and query execution
Quick Start
from sql_memory import SQLMemory, get_memory
mem = get_memory('cloud')
mem.remember('facts', 'vex_timezone', 'VeX is in EST/EDT timezone', importance=7)
entry = mem.recall('facts', 'vex_timezone')
results = mem.search_memories('timezone')
mem.queue_task('nlp_agent', 'analyze_document', '{"doc": "..."}', priority=3)
mem.log_event('training_complete', 'nlp_agent', 'Finished training cycle 42')
mem.store_knowledge('stamps', 'inverted_jenny', 'Rare 1918 misprint...', 'catalog')
Schema
All tables live in the memory schema (SQL Server database):
| Table | Purpose |
|---|
memory.Memories | Long-term curated memories with importance scoring |
memory.TaskQueue | Task queue for agent work items |
memory.ActivityLog | Event/activity logging for audit trail |
memory.KnowledgeIndex | Domain-specific knowledge store |
memory.Sessions | Session tracking for agents |
Memory Rollups
Hierarchical consolidation keeps memories fresh and relevant:
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:
- Summarizes source entries
- Creates a consolidated entry with back-references
- Reduces importance of source entries
- Tags sources as
rolled_up
Importance Scale
| Level | Meaning | Example |
|---|
| 1-2 | Ephemeral, archive | Old workspace file |
| 3-4 | Context, nice-to-know | Debug notes |
| 5-6 | Standard operational | Task completion |
| 7-8 | Important milestone | Architecture decision |
| 9 | Critical | System design choice |
| 10 | Permanent | Core identity/values |
API Reference
Memory Operations
| Method | Description | Example |
|---|
remember(cat, key, content, importance, tags) | Store a memory | mem.remember('facts', 'name', 'Oblio', 7) |
recall(cat, key) | Retrieve a memory | mem.recall('facts', 'name') |
search_memories(query, limit) | Semantic search | mem.search_memories('timezone', limit=5) |
forget(cat, key) | Delete a memory | mem.forget('facts', 'name') |
Task Queue
| Method | Description |
|---|
queue_task(agent, type, payload, priority) | Add a task |
claim_task(id) | Mark task as processing |
complete_task(id, result) | Mark task as completed |
fail_task(id, error, retries, max) | Fail with retry logic |
Activity Logging
| Method | Description |
|---|
log_event(type, agent, detail, extra) | Log an activity |
get_recent_activity(hours, agent) | Query recent events |
Configuration
Uses the same environment variables as sql-connector:
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
┌──────────────────┐
│ 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
