Lite SQLite - Lightweight Local Database

Ultra-lightweight SQLite database management optimized for OpenClaw agents with minimal RAM (~2-5MB) and storage overhead.

Why SQLite?

✅ Zero setup - No server, no configuration, file-based
✅ Minimal RAM - 2-5MB typical usage
✅ Fast - Millions of queries/second
✅ Portable - Single .db file
✅ Reliable - ACID compliant, crash-proof
✅ Cross-platform - Works everywhere Python works

Core Features

- In-memory mode for temporary data (even faster!)
WAL mode for concurrent access
Connection pooling
Automatic schema migration
Built-in backup/restore
Query optimization hints

Quick Start

Basic Database Operations

CODEBLOCK0

In-Memory Database (Fastest)

CODEBLOCK1

Performance Optimization

Essential Settings

CODEBLOCK2

Query Optimization

CODEBLOCK3

Predefined Schemas

Agent Memo Schema (Memory Store)

CODEBLOCK4

Session Log Schema

CODEBLOCK5

Cache Schema (TTL-based)

CODEBLOCK6

Advanced Features

Connection Pooling

CODEBLOCK7

Automatic Backup

CODEBLOCK8

Schema Migration

CODEBLOCK9

Performance Benchmarks

Typical Performance

Operation	Rows	Time (In-Memory)	Time (Disk)
Insert	10,000	0.05s	0.3s
Select (indexed)

10,000 | 0.001s | 0.01s | | Select (full scan) | 10,000 | 0.05s | 0.5s | | Update | 1,000 | 0.01s | 0.1s | | Delete | 1,000 | 0.01s | 0.1s |

Memory Usage

- Base Memory: 2-5MB
With 100K rows: ~10-15MB
With 1M rows: ~50-100MB
In-memory mode: Same as data size + overhead

Best Practices for OpenClaw Agents

1. Choose the Right Mode

CODEBLOCK10

2. Use Proper Indexes

CODEBLOCK11

3. Batch Operations

CODEBLOCK12

4. Use TTL for Expiring Data

CODEBLOCK13

5. Compact Database Periodically

CODEBLOCK14

DuckDB Alternative (Analytics)

For analytical queries (aggregations, joins on large datasets), consider DuckDB:

CODEBLOCK15

When to use DuckDB:

- Analytics on large datasets (>100M rows)
Complex aggregations and joins
Columnar data operations
Statistical analysis

When to use SQLite:

- Transactional operations
Small to medium datasets (<100M rows)
Point queries and updates
General-purpose storage

Common Patterns

1. Memo Storage

CODEBLOCK16

2. Session Persistence

CODEBLOCK17

3. Caching Layer

CODEBLOCK18

Error Handling

CODEBLOCK19

Size Optimization Tips

Reduce Storage

1. Use appropriate data types:

- INTEGER instead of TEXT for numbers - REAL instead of TEXT for floats - Use CHECK constraints for validation

2. Normalize data:

- Store JSON as TEXT - Use TEXT for variable-length strings - Avoid storing redundant data

3. Vacuum regularly:

CODEBLOCK20

4. Use WAL instead of journal:

   conn.execute("PRAGMA journal_mode=WAL")

Migration from Other Stores

From JSON Files

CODEBLOCK22

From CSV Files

CODEBLOCK23

Troubleshooting

Database Locked Error

CODEBLOCK24

Slow Queries

CODEBLOCK25

Large Database Size

CODEBLOCK26

CLI Tool

The bundled sqlite_cli.py provides command-line access:

CODEBLOCK27

Resources

- SQLite Documentation: https://www.sqlite.org/docs.html
Python sqlite3: https://docs.python.org/3/library/sqlite3.html
DuckDB: https://duckdb.org/docs/
Performance: https://www.sqlite.org/optoverview.html

Lite SQLite - 轻量级本地数据库

专为OpenClaw代理优化的超轻量级SQLite数据库管理，仅需极低RAM（约2-5MB）和存储开销。

为什么选择SQLite？

✅ 零配置 - 无需服务器，无需配置，基于文件
✅ 极低内存 - 典型使用仅2-5MB
✅ 高速 - 每秒数百万次查询
✅ 便携 - 单个.db文件
✅ 可靠 - 符合ACID标准，防崩溃
✅ 跨平台 - 支持所有Python运行环境

核心功能

- 内存模式用于临时数据（速度更快！）
WAL模式支持并发访问
连接池
自动模式迁移
内置备份/恢复
查询优化提示

快速开始

基本数据库操作

python
from sqlite_connector import SQLiteDB

创建数据库（自动启用WAL模式）

db = SQLiteDB(agent_data.db)

创建表

db.create_table(memos, { id: INTEGER PRIMARY KEY AUTOINCREMENT, title: TEXT NOT NULL, content: TEXT, createdat: TEXT DEFAULT CURRENTTIMESTAMP, tags: TEXT })

插入数据

db.insert(memos, [title=第一条备忘录, content=你好世界, tags=测试])

查询数据

results = db.query(SELECT * FROM memos WHERE tags = ?, (测试,))

更新数据

db.update(memos, id = ?, [content=已更新内容], (1,))

删除数据

db.delete(memos, id = ?, (1,))

关闭连接

db.close()

内存数据库（最快）

python

最快模式 - 仅使用RAM，无磁盘I/O

db = SQLiteDB(:memory:)

临时操作的理想选择

db.create_table(temp, {...})

数据仅在会话期间存在

适用于缓存、计算、临时存储

性能优化

关键设置

python
import sqlite3

WAL模式（预写日志） - 速度提升3-4倍

conn = sqlite3.connect(agent_data.db) conn.execute(PRAGMA journal_mode=WAL)

关闭同步（写入更快，正常关闭时防崩溃）

conn.execute(PRAGMA synchronous=NORMAL)

内存优化

conn.execute(PRAGMA cache_size=-64000) # 64MB缓存 conn.execute(PRAGMA page_size=4096)

临时存储使用RAM

conn.execute(PRAGMA temp_store=MEMORY)

查询优化

python

为频繁查询创建索引

db.create_index(memos, tags)
db.createindex(memos, createdat)

使用预编译语句（我们的封装器自动支持）

db.query(SELECT * FROM memos WHERE id = ?, (id,))

大数据集批量插入

db.batchinsert(memos, rowsdata)

预定义模式

代理备忘录模式（内存存储）

python
db.createtable(agentmemos, {
id: INTEGER PRIMARY KEY AUTOINCREMENT,
agent_id: TEXT NOT NULL, # 创建者代理ID
key: TEXT NOT NULL, # 查找键
value: TEXT, # 存储值
priority: INTEGER DEFAULT 0, # 检索排序
createdat: TEXT DEFAULT CURRENTTIMESTAMP,
expires_at: TEXT # 可选TTL
})

创建索引

db.createindex(agentmemos, agent_id) db.createindex(agentmemos, key) db.createindex(agentmemos, expires_at)

会话日志模式

python
db.createtable(sessionlogs, {
id: INTEGER PRIMARY KEY AUTOINCREMENT,
session_id: TEXT NOT NULL,
agent: TEXT NOT NULL,
message: TEXT,
metadata: TEXT, # JSON格式
createdat: TEXT DEFAULT CURRENTTIMESTAMP
})

db.createindex(sessionlogs, session_id)
db.createindex(sessionlogs, created_at)

缓存模式（基于TTL）

python
db.create_table(cache, {
id: INTEGER PRIMARY KEY AUTOINCREMENT,
key: TEXT UNIQUE NOT NULL,
value: BLOB, # 支持二进制数据
createdat: TEXT DEFAULT CURRENTTIMESTAMP,
expires_at: TEXT NOT NULL
})

自动清理过期条目

db.query(DELETE FROM cache WHERE expires_at < ?, (datetime.now().isoformat(),))

db.create_index(cache, key)
db.createindex(cache, expiresat)

高级功能

连接池

python
from sqlite_connector import ConnectionPool

并发访问连接池

pool = ConnectionPool(agentdata.db, maxconnections=5)

获取连接

conn = pool.get_connection()

使用conn...

pool.release_connection(conn)

自动备份

python

备份数据库

db.backup(agentdatabackup.db)

自动每日备份

db.auto_backup(backups/, daily)

模式迁移

python

添加列（如果不存在）

db.addcolumn(memos, updatedat, TEXT DEFAULT CURRENT_TIMESTAMP)

迁移数据

db.migrate(memos, { oldcolumn: newcolumn })

性能基准测试

典型性能

操作	行数	时间（内存模式）	时间（磁盘模式）
插入	10,000	0.05秒	0.3秒
查询（索引）

10,000 | 0.001秒 | 0.01秒 | | 查询（全表扫描） | 10,000 | 0.05秒 | 0.5秒 | | 更新 | 1,000 | 0.01秒 | 0.1秒 | | 删除 | 1,000 | 0.01秒 | 0.1秒 |

内存使用

- 基础内存：2-5MB
10万行数据：约10-15MB
100万行数据：约50-100MB
内存模式：数据大小+开销

OpenClaw代理最佳实践

1. 选择合适模式

python

临时操作使用:memory:

temp_db = SQLiteDB(:memory:)

持久存储使用文件数据库

persistdb = SQLiteDB(agentstorage.db)

2. 使用适当索引

python

始终为WHERE子句中的列创建索引

db.createindex(table, columnname)

复合查询创建多列索引

db.create_index(table, col1, col2)

3. 批量操作

python

避免逐条插入：

for row in rows:
db.insert(table, row) # 慢！

使用批量插入：

db.batch_insert(table, rows) # 快！

4. 使用TTL管理过期数据

python

自动清理旧数据

db.cleanupexpired(cache, expiresat)
db.cleanupold(logs, createdat, days=7)

5. 定期压缩数据库

python

大量删除后回收空间

db.vacuum() # 应在系统空闲时运行

DuckDB替代方案（分析用途）

对于分析查询（大数据集的聚合、连接），考虑使用DuckDB：

python
import duckdb

conn = duckdb.connect(:memory:)

复杂分析比SQLite更快

conn.execute( SELECT COUNT(*) as rows, AVG(value) as avg_value FROM large_table ).fetchall()

何时使用DuckDB：

- 大数据集分析（>1亿行）
复杂聚合和连接
列式数据操作
统计分析

何时使用SQLite：

- 事务性操作
中小型数据集（<1亿行）
点查询和更新
通用存储

常见模式

1. 备忘录存储

python
def savememo(db, agentid, key, value, ttl_hours=24):
expiresat = (datetime.now() + timedelta(hours=ttlhours)).isoformat()
db.insert(agent_memos, {
agentid: agentid,

轻量SQLite

轻量SQLite

Lite SQLite - Lightweight Local Database

Why SQLite?

Core Features

Quick Start

Basic Database Operations

In-Memory Database (Fastest)

Performance Optimization

Essential Settings

Query Optimization

Predefined Schemas

Agent Memo Schema (Memory Store)

Session Log Schema

Cache Schema (TTL-based)

Advanced Features

Connection Pooling

Automatic Backup

Schema Migration

Performance Benchmarks

Typical Performance

Memory Usage

Best Practices for OpenClaw Agents

1. Choose the Right Mode

2. Use Proper Indexes

3. Batch Operations

4. Use TTL for Expiring Data

5. Compact Database Periodically

DuckDB Alternative (Analytics)

Common Patterns

1. Memo Storage

2. Session Persistence

3. Caching Layer

Error Handling

Size Optimization Tips

Reduce Storage

Migration from Other Stores

From JSON Files

From CSV Files

Troubleshooting

Database Locked Error

Slow Queries

Large Database Size

CLI Tool

Resources

Lite SQLite - 轻量级本地数据库

为什么选择SQLite？

核心功能

快速开始

基本数据库操作

创建数据库（自动启用WAL模式）

创建表

插入数据

查询数据

更新数据

删除数据

关闭连接

内存数据库（最快）

最快模式 - 仅使用RAM，无磁盘I/O

临时操作的理想选择

数据仅在会话期间存在

适用于缓存、计算、临时存储

性能优化

关键设置

WAL模式（预写日志） - 速度提升3-4倍

关闭同步（写入更快，正常关闭时防崩溃）

内存优化

临时存储使用RAM

查询优化

为频繁查询创建索引

使用预编译语句（我们的封装器自动支持）

大数据集批量插入

预定义模式

代理备忘录模式（内存存储）

创建索引

会话日志模式

缓存模式（基于TTL）

自动清理过期条目

高级功能

连接池