编码代理的最佳数据库选择：用PostgreSQL管理状态，用混合搜索提升召回率。
最适合编程智能体的数据库：用于记录运行状态、工具调用及生成结果的 PostgreSQL，而在需要回溯时则搭配带有待处理队列的混合搜索层。
来源: The Best Database for Coding Agents? Postgres for State, Weaviate for Recall
为编程代理选择数据库时，应依据该代理一天的实际工作内容，而非其AI标签。那些会执行沙箱命令、调用工具、传输日志、生成文件、重试失败步骤并在中断后恢复的代理，本质上都是在处理各种附带效应的记录工作。对于这类记录任务，PostgreSQL是可靠的首选。而像Weaviate这样的向量存储则需在后续作为独立层加入，用于根据语义查找相似的过往故障及解决方案。
从一次工具调用开始
跟踪系统中单次工具调用的完整流程。在调用开始前，平台会将其标记为已启动，关联到对应的运行任务，预留一个幂等性键，记录所使用的沙箱环境，并将后续任务加入队列。调用完成后，平台会记录状态、输出元数据及结果文件，更新使用量统计，并推动上层运行任务向前推进。
这些操作属于同一逻辑流程。在事务处理中，它们要么一起提交，要么全部不提交，其他会话永远无法看到半完成的状态。现在考虑故障情况：某个进程在“工具处理完成”与“执行高级操作”之间崩溃，此时恢复过程必须是确定性的。如果重试两次，唯一约束应能拒绝重复的记录。当某个引用指向一个并不存在的运行记录时，外键也应拒绝该行数据。这些都不是什么特别复杂的情况，都是普通的数据库功能，编程工具会持续依赖它们，正因如此，它们的重要性远超过任何“人工智能原生”的营销宣传。
数据是关系型的
执行工具的核心实体并不复杂，它们彼此之间存在关联：
- 运行记录包含生命周期状态、负责人、工作空间、模型、时间戳、预算以及最终结果。
- 步骤是具有相互依赖关系的、已规划或已完成的工作单元。
- 工具调用会记录输入内容、输出结果、状态、延迟时间、重试次数以及幂等性键。
- 沙箱执行会描述执行环境、命令元数据、退出码、资源使用情况以及任务终止的原因。
- 事件用于生成仅可追加的历史记录，便于调试、流式处理和回放。
- 工件指向补丁、报告、生成的文件或对象存储位置。
- 检查点用于存储恢复工作流所需的信息。
每个元素都需要一个稳定的标识，并且要有与其他元素的明确关联。主键、唯一约束、检查约束以及外键使得无效状态难以产生，尤其是外键能够确保每一次工具调用都属于某次真实的运行，同时让每个生成物都能追溯到其创建者。
将用于协调的字段放在带有适当索引的类型化列中，这些字段包括状态、租户信息、运行编号、时间戳、尝试次数以及幂等性键。它们是调度、过滤、数据保留以及仪表板功能的基础。如果将这些字段隐藏在同一个结构混乱的大型 JSON 文档中，就很难强制执行相关规则。
jsonb 的适用场景
工具发展迅速。有的工具会返回编译器诊断信息，有的会生成浏览器事件，还有的会报告仓库元数据。为每种可能的字段都设置固定列会造成资源浪费，而 jsonb 则非常适合存储那些会变化的内容：工具参数、服务提供商的响应、沙箱配置以及模型元数据。PostgreSQL 可以通过运算符和路径表达式对 JSON 数据进行查询，并能使用 GIN 索引键和值，相关权衡已在官方手册中有详细说明。
有效的设计模式是在灵活的负载数据外层加上一个带类型约束的关系结构。所有用于保证数据完整性或支持常见查询的内容都存储在列中，而扩展数据则存放在 jsonb 中。这样就能避免两种极端情况：要么为每个实验都创建脆弱的单独列，要么使用不透明的文档存储方式，将所有数据关系都交给应用程序代码处理。
根据访问模式选择存储方式
并非所有内容都需要存储在主数据库中。简短的错误信息摘录、标准化的错误详情、退出码以及可搜索的摘要可存放在执行记录的旁边。而大量的控制台输出、仓库归档文件、二进制文件、截图以及构建输出通常会存储在对象存储中，PostgreSQL则通过持久的元数据与校验和来引用这些数据。
这种分离方式既能保持记录行的简洁，又能保留数据的来源信息。数据库依然是决定某个文件是否存在、由哪次运行生成、存储位置以及保留策略的权威来源，而对象存储则能以更低的成本处理大型且不可更改的数据块。需要注意的一点是：在流程中没有针对部分失败情况的恢复方案之前，绝不能认定上传已经成功。
事件历史记录也很有用。无需反复重写庞大的运行文档，只需记录有意义的状态变化，并保留简洁的当前状态行以便快速查询。历史记录可用于审计和故障诊断，而状态预测则服务于产品用户界面和调度器，这两者都可以存储在 PostgreSQL 中的同一事务中。
写入协议与引擎同样重要
实际应用中会遇到数据重复发送、工作进程崩溃、网络超时以及无法确认的工具运行结果等问题。选择数据库只是解决问题的一半。一个可行的协议应具备以下特点：
- 为可重试的操作设置由唯一约束支持的幂等性键。
- 将生命周期变化建模为有名称的状态转换，而非随意的状态更新。
- 每当部分可见性会导致错误时，需在同一个事务中提交相关行。
那些在为编程代理寻找最佳数据库的人所处理的不仅仅是聊天记录，还包括编辑文件、运行不可信代码、调用付费 API 以及发布更改等会引发副作用的操作。状态层必须确保每一次状态转换都是可检查且可恢复的。
何时检索层能发挥价值
PostgreSQL 依然是首选推荐。当产品有特定需求时，可添加专用的检索存储，以便按含义及精确文本搜索过往的执行历史。常见的查询包括“哪些在依赖项升级后失败的先前运行记录”、“类似此堆栈跟踪的错误该如何修复”以及“哪种工具序列能解决不稳定的测试问题”。
在那种搜索中，精确的标记依然很重要：异常名称、包版本、编译器代码、标志位、文件名以及哈希值。然而用户描述同一故障的方式却多种多样。纯关键词搜索会忽略概念间的关联，而纯向量相似度则可能低估工程师所依赖的精确字符串价值。混合搜索则能兼顾两者。Weaviate就是一种同时运行向量搜索和BM25关键词搜索，并将两种搜索的得分融合为单一排序结果的引擎，这样像ERR_MODULE_NOT_FOUND这样的精确代码能提供关键词层面的证据，而“运行时无法解析导入的包”这类描述则能提供语义层面的证据。
需明确界定各部分的边界。PostgreSQL负责管理标准的执行流程、工具调用、权限设置以及状态信息。异步工作进程会读取已提交的更改，从选定字段中构建检索文档，然后将其插入搜索索引中。检索结果会返回PostgreSQL的记录ID，这样应用程序就可以获取权威数据并在展示任何内容之前再次检查访问权限。即便索引构建出现延迟或需要重建，程序的执行正确性也不会受到影响。
只有当语义检索真正成为一项功能时，才有必要引入第二套系统。在此之前，PostgreSQL的全文搜索功能加上经过良好索引的结构化查询就已足够满足需求。
五部分参考结构
- PostgreSQL中的权威状态信息。包括执行流程、各步骤、工具调用结果、沙箱测试输出、工件元数据、检查点以及访问关系等。
- 对象存储中的大容量数据。 PostgreSQL负责存储数据位置、哈希值、内容类型、所有者以及保留策略相关数据。
- 已提交更改的暂存区。 工作进程可流式处理用户界面更新、安排后续任务，并构建搜索索引，而无需处理未提交的数据。
- 按需从向量索引或混合索引中检索文档。 检索结果包含摘要、标准化错误信息、指令、选定的日志片段、修复说明以及可筛选的元数据。
- 搜索结果通过PostgreSQL进行验证。 索引负责查找候选项，而数据库则始终是决定当前状态和权限的权威来源。
删除与保留操作也变得更易于理解。删除或遮蔽操作始于 PostgreSQL，随后传递到出站队列，移除相关对象并更新搜索投影，因此真实数据源永远不会产生歧义。
早期应避免的做法
- 仅仅因为使用了大语言模型就选择向量数据库。早期的运营问题大多是有结构的，比如某个状态下某个用户的操作记录、近期失败的步骤、与某次提交相关的缓慢工具调用或执行过程，这些都可以通过普通索引来解决。
- 用一个 JSON 数据块来存储所有智能体状态。这种做法虽然能带来短期便利，但会导致约束力薄弱、并发更新困难以及生命周期查询复杂。灵活的元数据尚可，但非结构化的记录系统则不可取。
检查清单
如果需要以下功能，请优先选择 PostgreSQL：
- 基于执行记录的多行 ACID 事务，
- 对运行过程、步骤、调用、用户及成果之间的关联进行强制约束，
- 安全的重试机制与并发控制，
- 按状态、时间、负责人、成本或结果进行简单过滤，
- 仍可查询的
jsonb元数据， - 可用于恢复与审计的持久化记录。
如果还需要以下功能，则需添加混合检索引擎：
- 基于含义的对历史运行记录及工具调用历史的搜索，
- 能够同等重视精确错误标识与相似表述的排序机制，
- 查找相关的事件、有效的修复方案及工作流程；
- 能够从标准记录中重新生成的检索层。
快速解答
向量数据库应作为主要后端吗？通常不必。主要工作负载涉及事务状态：运行过程、工具调用、结果输出、重试操作以及各种关联关系。向量存储则用于独立的检索任务。
jsonb 能够满足代理元数据的需求吗？对于不断变化的工具负载及供应商特定信息，只要使用带类型的列来存储标识符和生命周期相关字段，通常就足够了。它是对架构的补充，而非替代。
为何日志检索需要混合搜索方式？工程数据中既有精确的标记，也有自然语言内容。BM25 能够检索出确切的代码、软件包名称和文件名，而向量搜索则能关联描述同一故障的不同表述。
最佳的设计应是分工协作，而非关系型系统与向量系统之间的竞争。PostgreSQL承担着事务处理的核心功能：运行、日志记录、工具调用历史、元数据、检查点以及相关产物。当执行历史演变为知识资产时，叠加的混合检索层可提升查询效率——Postgres负责状态管理，而检索索引则用于提高查询速度。
相关阅读
- 2026年结束前值得比较的七款AI编程工具——对Claude Code、Cursor、Copilot、Codex、OpenCode、Devin和Antigravity CLI进行了对比：各自的优势、2026年8月的定价情况以及如何将它们组合使用。