使用 SQLite 存储 - AgentKit 文档

sqlite 后端把会话持久化到一个本地 SQLite 文件。它不依赖外部数据库服务，但与 local 不同，会话会落盘，因此可以跨进程、跨重启保留。

何时使用

单机部署且需要持久化；
本地开发但希望保留历史会话；
数据量不大、无需分布式访问的场景。

使用示例

from veadk import Agent, Runner
from veadk.memory.short_term_memory import ShortTermMemory

stm = ShortTermMemory(
    backend="sqlite",
    local_database_path="./short_term_memory.db",  # 数据库文件位置
)

agent = Agent(name="demo")
runner = Runner(agent=agent, short_term_memory=stm, app_name="memory_demo")

若数据库文件不存在，VeADK 会自动创建（包括所需的父目录），并把路径解析为绝对路径。也可以用 db_url 直接给出连接串，此时 backend 与 local_database_path 都会被忽略：

stm = ShortTermMemory(db_url="sqlite:///./test.db")

参数

ShortTermMemory 构造参数（sqlite 场景）

参数	类型	默认值	对 sqlite 是否生效	说明
`backend`	`str`	`"local"`	生效	设为 `"sqlite"` 选择本后端。传入已废弃的 `"database"` 也会被自动转为 `sqlite`。
`local_database_path`	`str`	`/tmp/veadk_local_database.db`	生效	SQLite 文件路径，会被解析为绝对路径；文件与父目录不存在时自动创建。
`db_url`	`str`	`""`	生效（覆盖）	直接给出连接串（如 `sqlite:///./test.db`）。一旦设置，将忽略 `backend` 与 `local_database_path`。
`backend_configs`	`dict`	`{}`	不生效	`sqlite` 后端不读取此项（仅 `mysql`/`postgresql` 使用）。
`db_kwargs`	`dict`	`{}`	不生效	`sqlite` 后端不透传此项；仅在使用 `db_url` 或 `mysql`/`postgresql` 时生效。
`after_load_memory_callback`	`Callable \| None`	`None`	生效	读取会话后触发的回调，入参为加载到的 `Session`。

环境变量

sqlite 后端不读取任何环境变量，所有配置均通过构造参数提供。需要分布式持久化？请改用 MySQL 或 PostgreSQL。

最后修改于 2026年9月19日