周末用SQLite，我给 AI Agent 配了一个文件型"本地大脑"

封面

【关键词：#SQLite #AI Agent #本地存储】

做一个 AI Agent 项目，需要给 agent 配上持久化层：要存会话历史、用户记忆、工具调用日志、任务队列，还要能跑简单检索。我没拉一套数据库服务，就用一个 SQLite 文件——一个 .db 把 agent 的所有状态都接住。两个月跑下来，稳定、可备份、可调试。 将agent执行的环境上下文信息，在SQLite存储，多agent可共享SQLite里的数据，SQLite 让 agent 的"记忆"和 agent 本身活在一起，不将各个数据分散到不同文件里。 PS : 这仅是短期实践的心得，后续AI的进步，SQLite也行会被抛弃。

01｜先看 SQLite 自己怎么说自己

打开 sqlite.org 首页，SQLite 给自己的定义只有一句话：

SQLite is a C-language library that implements a small, fast, self-contained, high-reliability, full-featured, SQL database engine. SQLite is the most used database engine in the world.

翻译过来就是：小、快、自给自足、高可靠、功能完整的 SQL 数据库引擎。官方口号更短——"Small. Fast. Reliable. Choose any three."（小、快、可靠，三选三）。

它和"大型数据库"解决的不是同一类问题。官方在 Appropriate Uses For SQLite 里直接点破定位：

SQLite strives to provide local data storage for individual applications and devices. SQLite emphasizes economy, efficiency, reliability, independence, and simplicity.

SQLite does not compete with client/server databases. SQLite competes with fopen().

SQLite 的竞争对手不是数据库服务器，是 fopen()——它和"打开一个本地文件"做同一件事，只是把这件文件的事做成了 SQL。读懂这句，就不用把它当成"小号数据库"来用——它本来就不是为那个场景设计的。

02｜SQLite 在 agent 上下文里真正值在哪——它是 agent 的"室友"

官方那句"SQLite 和 fopen() 抢饭碗"，放到 agent 场景里特别贴切。SQLite 不是 agent 的"远端数据库"，是 agent 的"室友"——它们活在同一个进程、同一个文件目录、同一个生命周期里。具体有四件事是别的方案给不了的：

  • 同进程，零网络：agent 进程里 import sqlite3，调用走的是本地 C 函数，不走 TCP、不走 HTTP、不走驱动握手。读一次会话记录，就是一次进程内的函数调用。
  • 同生命周期：agent 启动 SQLite 就开，agent 退出 SQLite 就关。不会出现"agent 已挂、数据库还在另一台机器上空跑"的状态错位。
  • 同文件系统：备份就是 cp agent.db，迁移就是 rsync，schema 版本管理直接 git diff。agent 整个部署单元压成一个文件夹加一个 .db 文件，本地、CI、单机 VPS 三种环境用同一份配置。
  • 同故障域：agent 进程崩溃、容器被 kill、机器重启——SQLite 文件保持一致；下次 agent 拉起来，原样继续，不用做"数据库重启 → agent 重连"那种对账。

说白了，SQLite 让 agent 的"记忆"和 agent 本身活在同一个空间里。这件事看着小，但带来的可调试性和可移植性，是任何"远端数据库 + agent"组合都给不了的。

03｜我在 agent 项目里具体怎么用

一张 agent.db，四张表承担全部持久化：

  • 会话与记忆：messages 表按 session_id 入库所有对话；memories 表存用户长期事实（语言、职业、家人姓名），每轮结束让 LLM 抽取后 INSERT OR REPLACE，schema 校验放应用层。
  • 任务队列：多 agent 协作时它就是"共享黑板"，worker 用 UPDATE ... WHERE status='pending' 抢单。SQLite 写串行的特性在这里天然合适——所有写都串行执行，恰好等于"一次只准一个 worker 改一条记录"。
  • FTS5 全文检索：内部文档问答这种强关键词场景，Python 内置的 SQLite 默认启用 FTS5，一行 CREATE VIRTUAL TABLE docs USING fts5(title, content) 就能搜，MATCH 'python AND 类型' 支持布尔语法，毫秒级返回。
  • 工具调用审计：每次调工具的输入、输出、耗时、错误码全部入库。出问题时一句话查"昨天那条 query 卡在哪一步"。

加上 PRAGMA journal_mode=WAL + busy_timeout=5000，整个 agent 持久化层就齐了——agent 这一侧只看到一个 .db 文件，没有数据库进程、没有连接池、没有 DDL 迁移工具。

04｜坑和我的判断

SQLite 不是没坑，真实撞上的一个最关键：SQLite 是弱类型——列声明的类型只是"提示"，可以塞任意类型进去。schema 校验必须放应用层，我用 Pydantic 在落库前强校验一次。再加上并发写串行、没有 GRANT，多租户场景得提前规划 auth。

  • 单机 agent、单进程、读多写少——SQLite 是最对的选择。
  • 高并发写、TB 级数据、多机共享——SQLite 不是它的战场。

SQLite 帮我把 agent 的持久化从"基础设施"打回"普通文件"——这件事本身就值一个晚上。

工具版本：SQLite 3.45.1（Python 3.11 内置 sqlite3） 测试环境：macOS / Python 3.11 / 单进程 agent 测试者：猫咪不吃愚

本文事实参考 SQLite 官方首页、Appropriate Uses For SQLite、Python sqlite3 文档。