LumiBot / 记忆与回放
LumiBot 的记忆与回放：AI 决策凭什么被复盘
一个 AI 交易策略最容易出问题的地方不是下单，而是事后说不清：为什么买？当时看到了什么？上一轮的风险笔记有没有被考虑？如果这些答案只存在于模型的一次输出里，那这套系统就只是一个黑箱演示。LumiBot 的做法是给 agent 加一条可落盘的记忆层——提案、风险笔记、最终决策、教训、开着的投资论点都能写进本地记忆，并在回测时导出成可读文件。
据官方 docs/AI_AGENT_BUILTIN_TOOLS.md，记忆在策略运行期以 SQLite 落地，另外导出 三个 Parquet 产物；记忆事件与检索记录会带上 agent_name 与 model_call_id，也就是「哪一次模型调用产生了这条记录」可以追溯。官方同时提供 replay cache：回测时可以回放已保存的决策，不必再付一次模型调用。
但这里有两个非常容易被读错的点，本站先把它们写在最前面：① 回放省的是模型调用，不是省掉判断——它回答「当时为什么这么选」，不回答「换个模型还会不会这么选」；② 记忆只保证可追溯，不保证决策正确。本站未在本机复现回放行为，相关表述均标注为「依据官方文档与源码文件存在性」。
- 记忆工具清单、产物文件名与溯源字段：出自官方
docs/AI_AGENT_BUILTIN_TOOLS.md（2026-09-22 采集） - 回放（replay cache）：出自官方
llms.txt描述与仓库lumibot/components/agents/replay_cache.py文件存在性 - 环境变量：出自官方
docs/ENV_VARS.md，未实测默认值 - 本站未运行 agent、未实盘下单、不做收益声明
记忆到产物
从一次决策到可复盘文件
docs/AI_AGENT_BUILTIN_TOOLS.md，2026-09-22 采集）。示意图只重述官方文档中的机制，不代表本站已在本机复现；具体文件名与字段以官方实现为准。AI 策略最大的风险不是做错，而是说不清
把大模型接进交易循环之后，「可解释」这件事会从「代码怎么写」变成「那一轮它到底读到了什么」。官方给出的答案是给 agent 一套显式的记忆与产物机制，而不是让它把上下文留在提示词里。
记忆解决的是「追问链」
当你想问「上周三为什么买这只」时，答案不应该靠翻日志拼凑。官方把提案、风险笔记、最终决策、教训、投资论点分成不同类别的记忆事件，并给每条事件标上来源 agent 与模型调用 ID，这样追问链才有起点。
记忆不解决「决策质量」
它保证的是可追溯，不是正确。记录得再完整，也改变不了「模型判断可能错」这件事。把记忆层当成可信度证明，是本站最想拦下来的误读。
回放解决的是「成本与对照」
官方描述回测可以从缓存回放相同运行、不再调用模型。它的价值在于让同一批决策可被反复审视与对账，而不是让策略「更准」。
| 维度 | 没有记忆层会怎样 | 有记忆层能怎样 | 注意点 |
|---|---|---|---|
| 买入理由 | 只剩一句「模型决定买入」，无法追问依据 | 提案、看多理由与风险笔记分条留痕 | 留痕不等于理由成立；仍需自己判断证据质量 |
| 持仓期管理 | 加仓、减仓时重复论证同一个问题，甚至自我矛盾 | 官方建议先检索该标的的 open thesis 再动手 | 这是官方给出的建议流程；不做会有非阻断告警，但不会拦下订单 |
| 迭代对照 | 换了提示词或模型后，无法比较「上一版怎么想」 | 回放缓存可以复现已保存的决策运行 | 回放复现的是当时的决策，不是当时的市场结果 |
| 失败复盘 | 亏损原因只能靠猜，教训留不下来 | 有专门的教训类记忆工具，可写入并再检索 | 写进去的是「模型总结的教训」，需要人工复核 |
| 成本控制 | 每次重跑都重新付费调用模型 | 回放相同运行不需要再调用模型 | 省的是调用费，不是跳过全部计算；数据与指标仍要算 |
| 审计与交接 | 队友接手时看不到决策轨迹 | events / retrievals / state 三类产物可离线查看 | 产物里可能含标的与策略细节，别随手外发 |
| 责任边界 | 「是模型自己决定的」变成免责话术 | 可查哪一次调用、哪个 agent 写了哪条记录 | 溯源记录能定位过程，不构成任何投资建议或责任转移 |
工具是分流的，不是一个大号记事本
官方把记忆工具按「用途」切开：研究想法、风险笔记、最终决策各走各的入口，另有检索与「投资论点」的生命周期管理。理解这套分流，才不会把决策记录写成草稿本。
| 工具 | 用途 | 谁能用 | 注意点 |
|---|---|---|---|
remember | 写入一条通用记忆 | agent | 最通用也最容易被滥用；官方对提案、风险、决策另有专用入口，别都用它兜底 |
search_memory | 检索记忆，支持按 kind / symbol / status 过滤 | agent | 官方建议在操作已持有的标的之前，先按该 symbol 检索 open thesis |
remember_proposal | 记录研究阶段的想法 | agent | 用途是「提案」，不要与最终决策混写 |
remember_risk_note | 记录看空理由 / 风险笔记 | agent | 官方明确它是 bear-case 笔记的入口，适合承载反方意见 |
remember_decision | 记录最终交易决策 | 仅可交易 agent | 权限被关闭时会连同其它变更类工具一起被移除（见 权限分界）；官方要求它只用于最终决策 |
remember_lesson | 沉淀教训 | agent | 教训是模型写的总结，不是客观结论，后续引用前要复核 |
open_thesis | 开一个投资论点 | agent | 论点有生命周期，开了就要负责后续更新或关闭 |
update_thesis | 更新已有论点 | agent | 用于追加证据或调整判断，比新开一条更利于追溯 |
close_thesis | 关闭论点 | agent | 平仓后不及时关闭，会让后续检索拿到过期论点 |
orders_submit_order 会在订单提交后自动记录一条 order.submitted 记忆事件。也就是说「提交过订单」这件事不需要 agent 额外调用工具去写。但要注意：自动记录的是「提交」这个动作，不是「成交」。成交与否仍要看订单状态里的 is_filled，见 下单与成交。运行期是 SQLite，回看时是三个 Parquet 文件
官方把记忆分成「运行期存储」与「导出产物」两层：策略跑着的时候用 SQLite，跑完可以把记忆导出成 Parquet 供离线查看。下面是官方文档列出的文件名与溯源字段。
*_memory_events.parquet—— 记忆事件流（写入了什么）*_memory_retrievals.parquet—— 检索记录（哪一次读取了哪些记忆）*_memory_state.parquet—— 记忆状态（每个 agent 状态的快照）
| 产物 | 记录了什么 | 关键字段 | 适用场景 | 注意点 |
|---|---|---|---|---|
| 运行期 SQLite 库 | 策略运行期间 agent 的全部记忆读写 | 官方文档未逐一列出表结构 | 运行中调试、观察 agent 是否按预期检索 | 属于运行期间存储，不是长期归档；落盘位置可用 LUMIBOT_MEMORY_DIR 指定 |
*_memory_events.parquet | 写入了哪些记忆事件（含提案、风险笔记、决策、教训等） | agent_name、model_call_id | 复盘「当时是谁、在哪一次调用里写了什么」 | 事件多不等于决策质量高；记录完整度靠人工检查 |
*_memory_retrievals.parquet | 哪一次运行读到了哪些记忆 | agent_name、model_call_id | 核对「说要先查 open thesis」这类流程有没有真的执行 | 检索记录只证明「读了」，不证明「读了就改对判断」 |
*_memory_state.parquet | 记忆状态的整体快照 | 官方文档未逐一列出字段 | 快速对比两轮回测之间 agent 状态差异 | 快照字段以官方实现为准；本站未导出过该文件 |
order.submitted 事件 | 订单提交后自动写入的一条记忆事件 | 由订单工具自动产生 | 确认「agent 确实提交过订单」 | 只证明提交动作发生，不证明成交，也不证明价格合理 |
溯源字段 agent_name | 区分是哪个 agent 写的 | —— | 多 agent（研究员 / 看多 / 看空 / 交易员）分工排查 | 命名混乱时溯源价值打折，建议固定命名 |
溯源字段 model_call_id | 关联到具体某次模型调用 | —— | 模型版本或提示词变更后的对照分析 | 它是调用标识，不是模型质量评分 |
回放省的是模型调用，不是省掉判断
官方对回放的描述只有一句：Agentic backtests can replay identical runs from cache without another model call. 仓库里对应 lumibot/components/agents/replay_cache.py。这句话很短，但边界很明确。
| 你想问的问题 | 回放能回答 | 回放不能回答 | 注意点 |
|---|---|---|---|
| 上一轮它为什么选了这只标的 | 能——已保存的决策与理由可被重放查看 | 不能——不能证明这个理由是对的 | 把「有理由」与「理由正确」分开看 |
| 同一份策略再跑一次结果会不会一致 | 能——缓存保证相同运行的决策可复现 | 不能——不能保证在真实券商侧同样成交 | 回放复现的是决策，不是市场执行结果 |
| 换个模型或改提示词后会怎么选 | 不能——这需要真的调用新模型 | 不能——回放不会产生新判断 | 这正是回放的价值反向：省钱的代价是不产生新信息 |
| 这一轮回测花了多少模型调用费 | 能——回放相同运行不需要再调用模型 | 不能——不能替你估算不同数据区间的成本 | 省的是调用费；数据、指标与撮合仍要计算 |
| 回测收益能不能直接当实盘预期 | 不能——回放不是收益放大器 | 不能——回放不改善策略表现 | 任何历史回测数字都不构成未来收益预期 |
| 能不能用它替代成交验证 | 不能——它不接触券商 | 不能——无法证明订单成交 | 成交要看 is_filled，与回放无关 |
| 回放与「重新跑一遍模型」差在哪 | 能——前者读缓存，后者重新推理 | 不能——两者都不保证结论稳定 | 要对照模型差异，必须真的重新调用；要对照同一批决策，才用回放 |
llms.txt 的描述与仓库中 replay_cache.py 文件的存在性。本站未在本机复现回放行为，也没有验证缓存命中条件、缓存失效策略与跨版本兼容性——这些都以官方实现为准。如果你要用它做成本敏感的实验，请先在自己环境里用小样本验证缓存是否真的命中。记忆与 agent 运行时都由什么文件组成
官方把 agent 运行时放在 lumibot/components/agents/，本机清点该目录共 15 项。下表把与本页主题相关的模块列出，并标注哪一列的用途有官方文档直接支持、哪一列是按文件名与文档对应关系推断。
| 组件 | 与本页主题相关的用途 | 依据强度 | 注意点 |
|---|---|---|---|
runtime.py | agent 运行时主体（官方称框架内置 AI agent runtime） | 官方描述支持 | 运行时行为细节需读源码，官方文档未逐项展开 |
manager.py | agent 的创建与管理（self.agents.create(...) 相关） | 按文件名与文档对应推断 | 本站未读实现，具体职责以源码为准 |
replay_cache.py | 决策回放缓存（本页第 4 节主题） | 官方描述 + 文件存在性 | 缓存命中条件未实测 |
rules.py | 确定性规则（与 example_strategies/agent_rules/*.rules.json 呼应） | 按文件名与示例目录对应推断 | 示例目录下有 5 份 .rules.json，说明该机制确有落地形态 |
duckdb_tools.py | DuckDB 查询工具（官方推荐用它做时序分析而不是把大段 bar 塞进提示词） | 官方描述支持 | 把大数据塞进提示词既贵又易失真 |
docs_tools.py | 文档检索工具 | 官方工具清单支持 | 检索结果质量取决于文档本身 |
managed_gateway.py | 托管侧 AI 网关（对应 LUMIBOT_AI_GATEWAY_* 变量） | 官方环境变量文档支持 | 属托管（BotSpot）路径，不是本地开源必用 |
skills.py 与 skills/ | 运行时技能加载；目录内有 options-trading、research-data、stock-trading 三个内部技能 | 目录清单 + setup.py 打包声明 | 这是 LumiBot 自带的运行时技能，与 EasyClaw 的技能体系无关 |
| 其余 6 项 | __init__.py、asset_resolution.py、builtins.py、schemas.py、tool_context.py、tools.py | 仅目录清单 | 本站未逐个核对实现，不据文件名下结论 |
4 个相关环境变量，和 7 种常见误用
记忆一旦进入实际运行，就变成运维问题：存哪里、能写多长、能调用几次、托管网关要不要开。下面这些变量都出自官方 docs/ENV_VARS.md，本站只证明它们被文档化，未实测默认值。
| 环境变量 | 作用 | 什么时候要改 | 注意点 |
|---|---|---|---|
LUMIBOT_MEMORY_DIR | 指定记忆落盘目录 | 需要把记忆放到持久盘或指定数据目录时 | 放进临时目录或容器可写层，重启后记忆会丢 |
LUMIBOT_AGENT_MAX_MODEL_CALLS | 限制 agent 的模型调用次数 | 跑长区间回测或成本敏感实验时 | 官方文档未给出默认值；上限设太小会截断推理过程 |
LUMIBOT_AGENT_MAX_RUN_ATTEMPTS | 限制 agent 单次运行的重试次数 | 外部工具（新闻、宏观接口）不稳定时 | 重试会放大调用成本，要和上一个变量一起看 |
LUMIBOT_AGENT_MEMORY_NOTE_MAX_CHARS | 限制单条记忆笔记的长度 | 笔记被截断影响可读性时 | 放长不等于更好；长笔记检索命中率未必高 |
LUMIBOT_AI_GATEWAY_URL | 指向托管 AI 网关地址 | 使用 BotSpot 托管路径时 | 本地自托管通常不需要；误配会导致调用失败 |
LUMIBOT_AI_GATEWAY_TOKEN | 托管网关凭据 | 同上 | 不要提交进仓库或截图；密钥泄露等同于账户风险 |
| 常见误用 | 后果 | 怎么发现 | 注意点 |
|---|---|---|---|
| 把记忆目录放在临时目录 | 容器或临时盘清理后记忆全部丢失，回放无从谈起 | 重跑后 *_memory_*.parquet 变空或找不到 | 先固定持久化目录再开始跑长回测 |
把 remember_decision 当草稿本 | 最终决策记录里混入大量研究想法，复盘时无法分辨 | events 里决策类事件数量远超交易次数 | 提案走 remember_proposal，风险走 remember_risk_note |
| 以为回放等于「重跑一遍模型」 | 误判模型变更的影响，得出错误结论 | 换了模型但回放结果一字不变 | 要评估模型差异必须真的重新调用 |
| 把托管网关变量当成本地必需 | 本地自托管环境配置报错或调用失败 | 本地运行时不带托管凭据也能跑通，说明它不是必需项 | 分清「开源框架」与「托管服务」两条路径 |
| 不设模型调用上限 | 长区间 + 多 agent 的组合会迅速推高调用成本 | 账单与回测区间长度成正比异常增长 | 先小样本试跑，再放大区间 |
| 用只读 agent 却期待写决策 | remember_decision 工具根本不存在，流程中断 | 工具清单里查不到该工具 | 权限开关同时决定能否下单与能否写决策 |
| 只看不回看产物 | 记忆写了却没人读，等于没有记忆层 | 没有任何针对 retrievals 的核对动作 | 把「读产物」写进你的复盘流程，才算闭环 |
关于 LumiBot 记忆与回放的高频问题
以下回答基于 2026-09-22 对官方仓库文档与本机文件清点的核对；记忆机制与产物字段以官方实现为准。本站未运行 agent、未实盘下单，也不做收益声明。
记忆到底存在哪里？会不会一关就没了？
官方文档写明：记忆在策略运行期以 SQLite 落地，另外导出三个 Parquet 产物（*_memory_events.parquet、*_memory_retrievals.parquet、*_memory_state.parquet）。所以它有别于「只存在提示词上下文里」的做法。但落盘位置是运维问题：官方环境变量里提供了 LUMIBOT_MEMORY_DIR 用于指定目录，本站未实测其默认值。如果你把它放在临时目录或容器可写层，重启后记忆很可能丢失——这一点以你的实际部署方式为准。
回放（replay cache）到底能省什么？
官方描述是：agentic 回测可以从缓存回放相同运行，不再产生一次模型调用，对应 lumibot/components/agents/replay_cache.py。省下的主要是模型调用成本。它不省数据、指标与撮合的计算，也不会改善策略表现。本站未在本机复现回放，缓存命中条件与失效策略均以官方实现为准。
有了记忆和回放，回测结果就更可信了吗？
不是同一件事。记忆解决的是「可追溯」，回放解决的是「决策可复现」，两者都不解决回测本身是否含未来信息。指标的时间安全是另一个独立问题——官方曾公开过一个 offset=-1 的 SMA 因整段序列一次计算而从 25 变成 1510 的回归案例。建议把两件事分开验收：先确认指标口径安全，再看决策是否可追溯。详见未来函数与时间安全。
为什么官方要求交易前先检索 open thesis？
因为 agent 在加仓、减仓或卖出已持有的标的时，很容易重复论证、甚至推翻自己前面的判断。官方因此建议先调用 search_memory（支持按 kind / symbol / status 过滤）查该标的的 open thesis；如果跳过这一步，Lumibot 会记一条非阻断告警。注意「非阻断」的含义：它只是留痕提示，不会拦下订单。这是流程建议，不是安全闸门。
记忆里写的「决策」能当成交证据吗？
不能。订单提交后框架会自动记录一条 order.submitted 记忆事件，但它证明的是「提交动作发生过」，既不等于成交，也不等于价格合理。成交判定要看订单状态里的 is_filled；提交成功、接口返回 200、轮询超时都不能当作成交。详见下单与成交。
LumiBot 自带的 agent skills 和 EasyClaw 的技能是一回事吗？
不是。LumiBot 在自己的包内含三个运行时技能（options-trading、research-data、stock-trading，位于 lumibot/components/agents/skills/），作用是在特定场景提示 agent 按流程办事。EasyClaw 的技能体系是完全独立的另一套东西，与 LumiBot 无关联；本站据本机技能目录核对，LumiBot 与 EasyClaw 之间没有已证实集成。上面提到的两个工具名相同或相近，也请不要混为一谈。
我要不要在实盘里开记忆？
官方把记忆设计成可在回测与实盘同一套策略里使用，但本站不替你做这个决定。可以明确的是三件事：① 记忆会落盘，涉及标的与策略细节，注意文件权限与留存策略；② 托管网关凭据（LUMIBOT_AI_GATEWAY_TOKEN 等）不要进仓库、不要出现在截图里；③ 记忆与回放都不构成投资建议，也不改变交易风险。实盘前请以官方文档与你自身的合规要求为准。