agent-memory-sqlite

Long-term memory for AI agents: one SQLite file, no server, no cloud.

A single-file memory store you can hand to any agent — copy it, back it up, move it to another machine. Built for Chinese first (FTS5 trigram + sliding-window queries), with bi-temporal validity, confidence scores, and three-lane RRF retrieval.

一个文件就是一台记忆机器。无服务、无云、无依赖地狱；拷走就能用，任何 agent 调 CLI 或 MCP 即可。

~800 lines of Python · SQLite + sqlite-vec + fastembed · no framework, no API server required

为什么不是又一个向量库

Related MCP server: personal-memory-mcp

快速开始

pip install sqlite-vec fastembed

python brain.py init
python brain.py add "用户的时区是 Asia/Shanghai，默认用中文" --kind preference
python brain.py recall "他大概在哪个时区"
python brain.py inject "他大概在哪个时区"     # 直接能塞进提示词的一块

首次运行会下载 BAAI/bge-small-zh-v1.5（约 100MB）。国内建议先设：

export HF_ENDPOINT=https://hf-mirror.com

命令

接进你的 agent

① CLI（任何语言都能调）

python brain.py inject "当前这轮用户说的话"

② stdio MCP（Claude Desktop / Claude Code / 任何 MCP 宿主）

{
  "mcpServers": {
    "memory": {
      "command": "/absolute/path/to/python",
      "args": ["/absolute/path/to/mcp_server.py"]
    }
  }
}

暴露 recall(query,k) / inject(query,budget) 两个工具，和 brain://stats / brain://recall/{query} 资源。 不设 BRAIN_URL 时进程自己开库，不需要任何后台服务。

③ HTTP（多进程共享一个库）

python brain.py serve --port 8766
curl "http://127.0.0.1:8766/inject?q=..."

设计要点

双时间（bi-temporal）：valid_from / valid_to。用户换工作、换住址、改偏好之后，旧事实不会跟新事实一起被召回。valid_to 非空即不进召回。

置信度：importance 回答"多重要"，confidence 回答"多可信"。用户亲口说的 0.95，模型抽出来的 0.75，对话原始流水 0.60。抽取错了能一条条降下去。

三路 RRF：词法、语义、质量三个通道各自排名，按名次投票（1/(60+rank)）。单看余弦会被"语义泛化"骗，单看关键词会被短词误命中骗。注意 RRF 只用于排序，不要拿绝对值当阈值——满分也只有 ≈0.049。

中文特化：FTS5 trigram 分词 + 查询侧三字滑窗。中文没有空格，不切窗的话整句当一个 token，MATCH 永远 0 命中——这是中文场景最常见的坑。

注入前置检查：check() 先问"这问题答得了吗"，答不了返回空字符串。不相关的问题 token 消耗归零，也不会把五条无关记忆塞进上下文。

局限

• 单机单文件。要多人并发 / 上百万条，换 Milvus、Qdrant 这类。

• 语义模型是 bge-small，5 亿参数以下，泛化强但精度一般。要更准就换更大的 embedding。

• ingest / skills 只对 Hermes 格式的 state.db / skills/ 有效；别的宿主用 add 或自己写导入。

• 没做加密。私密数据请自己管好文件权限。

License

MIT