把应用会话历史存入 SQLite

通过 bub-tapestore-sqlalchemy，把 Bub 应用的会话历史存入本地 SQLite 数据库。插件替换应用默认的文件存储，你仍可用 ,tape.info 和 ,tape.search 检查记录。

本指南通过 BUB_* 设置为 Bub CLI 配置插件。在自己的 Python 程序中，可以构造 SQLAlchemyTapeStore 并直接传给 core.Agent，具体用法见在 Agent 中复用插件。Tape 与上下文说明两种用法共用的存储行为。

前置条件

你需要：

• Bub 已安装，且 bub --help 可以运行（参考 安装）。
• 一个工作区，其中 bub run "What tools do you have?" 能调用已配置的模型。
• sqlite3 CLI，用于可选的数据库检查。

1. 安装插件

如果还没有配置过 BUB_HOME，先把它设成绝对路径：

export BUB_HOME="${BUB_HOME:-$HOME/.bub}"

bub install bub-tapestore-sqlalchemy@main

确认 Bub 加载了入口点：

bub hooks

provide_tape_store: builtin, tapestore-sqlalchemy

2. 把 Bub 指向本地 SQLite 数据库

插件默认使用 <BUB_HOME>/tapes.db。教程里换一个方便找到和清理的位置：

export BUB_TAPESTORE_SQLALCHEMY_URL="sqlite+pysqlite:///$PWD/bub-tapes.db"

这个 URL 会传给 SQLAlchemy。sqlite+pysqlite 方言使用 Python 标准库里的 SQLite 驱动，因此不需要额外安装数据库驱动。

3. 跑一个 turn

跑一个小的自然语言任务，然后让 Bub 检查刚刚写入的 Tape：

bub run "Reply with one short sentence: hello from local SQLite."
bub run ",tape.info"

name: 86774b31b96845a4__0b871d5e50e7c192
entries: 9
anchors: 1
last_anchor: session/start
entries_since_last_anchor: 8
last_token_usage: 4106
last_token_cache_hit_rate: 72.50%

具体 Tape 名称和数量取决于你的工作区与模型调用，但命令应当输出 Tape 名称、至少一个锚点，以及 session/start 之后写入的条目。

4. 检查数据库

用标准 CLI 打开 SQLite 文件：

sqlite3 "$PWD/bub-tapes.db" "SELECT name, last_entry_id FROM tapes;"

86774b31b96845a4__0b871d5e50e7c192|9

last_entry_id 记录每条 Tape 当前写到的最高条目 ID。也可以检查锚点行：

sqlite3 "$PWD/bub-tapes.db" \
  "SELECT entry_id, anchor_name, entry_date FROM tape_entries WHERE kind = 'anchor';"

1|session/start|2026-05-15T01:27:57Z

Bub 现在将同样的 Tape 条目写入 SQLite，替代应用默认的文件存储。

5. 扩展后端

bub-tapestore-sqlalchemy 通过 BUB_TAPESTORE_SQLALCHEMY_URL 配置，因此同一个插件也可以指向其他 SQLAlchemy 支持的数据库 URL，前提是运行 bub 的环境中安装了对应方言与驱动。不同驱动可能需要兼容性设置或特定处理；用于长期 Tape 之前，请先用本教程里的 ,tape.info 流程验证后端行为。

如果你需要更专门的 SQLite 存储，可以参考 bub-tapestore-sqlite。它基于 sqlite-vec，并支持利用向量嵌入做 Tape 检索。

清理

unset BUB_TAPESTORE_SQLALCHEMY_URL BUB_TAPESTORE_SQLALCHEMY_CONNECT_ARGS
rm -f "$PWD/bub-tapes.db"

下一步

• 使用 Tape 与 Phoenix 观察 Bub：把持久化 Tape 和 GenAI 遥测配合使用。
• Tape 与上下文：理解 Bub 记录什么，以及如何重建上下文。
• 插件：bub-tapestore-sqlalchemy 遵循的插件契约。