sql-memory

# 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): | 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: 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 | 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