SQL Memory

Other

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 APIs. Built on sql-connector for reliable parameterized SQL execution.

Install

openclaw skills install 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

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:

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