seekdb：AI Agent 的记忆与混合检索

seekdb 是 OceanBase 推出的 AI 原生数据库：MySQL 兼容、支持嵌入式运行、向量 + 全文 + 标量混合检索，并提供 FORK DATABASE 写时复制沙箱，适合作为 AI Agent 的状态存储（state store）。

何时使用

需要给 Agent 增加长期记忆 / 会话状态存储，并要求写入后毫秒级可检索
需要向量相似度、全文匹配、标量过滤在同一条 SQL 里完成
需要让 Agent 在隔离沙箱中试错，再把结果合并回主干（FORK / MERGE）
本地开发想要一个嵌入式数据库，不想起服务、配 Schema、配 Embedding 服务

不适用：OceanBase 分布式集群运维、超大规模离线分析、非 SQL 场景。

1. 安装与运行形态

# Python SDK（推荐用于 AI/ML）
pip install -U pyseekdb

# Docker 快速测试
docker run -d --name seekdb -p 2881:2881 -p 2886:2886 \
  -v ./data:/var/lib/oceanbase oceanbase/seekdb:latest

# 云服务（零安装，7 天免费）
curl -X POST https://d0.seekdb.ai/api/v1/instances

三种形态互不影响：嵌入式（进程内）、单机服务器（2881 端口）、OceanBase 分布式模式。

2. Agent 记忆模式（持续写入 + 即时检索）

import pyseekdb

client = pyseekdb.Client(path="./agent_state.db")          # 嵌入式模式
memory = client.get_or_create_collection(name="episodic")

for step in agent.run():
    # 持久化一条观察
    memory.upsert(ids=[step.id], documents=[step.observation])

    # 写入后毫秒级检索相关上下文（增量 HNSW，无需等待后台重建）
    relevant = memory.query(query_texts=step.next_query, n_results=5)

    agent.act(relevant)

要点：seekdb 的异步索引流水线（Change Stream）把写入与索引构建解耦，写入提交即返回；两级 HNSW（增量 + 快照）保证新写入的向量立即可检索，高并发下 P99 平稳。

3. 一条 SQL 完成混合搜索

CREATE TABLE articles (
  id        INT PRIMARY KEY,
  title     TEXT,
  content   TEXT,
  embedding VECTOR(384),
  FULLTEXT INDEX idx_fts (content) WITH PARSER ik,
  VECTOR   INDEX idx_vec (embedding) WITH (DISTANCE=l2, TYPE=hnsw, LIB=vsag)
) ORGANIZATION = HEAP;

-- 向量相似度 + 全文匹配 + 标量过滤，同一条查询完成
SELECT id, title,
       l2_distance(embedding, '[0.12, 0.34, ...]') AS dist
FROM articles
WHERE MATCH(content) AGAINST('quarterly report')
  AND author_id = 42
  AND created_at > '2026-01-01'
ORDER BY dist APPROXIMATE LIMIT 10;

设计要点：向量、全文、标量条件统一下推到同一执行计划，避免客户端 N+1 合并和结果拼接。

4. Agent 沙箱：FORK / MERGE

-- 秒级快照，零数据拷贝（内核级 COW）
FORK DATABASE agent_state TO agent_sandbox_42;

-- 在沙箱中自由读写，甚至改表结构
USE agent_sandbox_42;
INSERT INTO memory (session_id, embedding, content) VALUES (...);

-- 将成果合并回主线；策略：FAIL / THEIRS / OURS
MERGE TABLE agent_sandbox_42.memory INTO agent_state.memory STRATEGY THEIRS;

-- 或直接丢弃沙箱
DROP DATABASE agent_sandbox_42;

适用场景：Agent 需要试错、回滚、并行分支探索时，用数据库级快照替代应用层的保存/恢复逻辑。

5. 连接与排障清单

服务器模式默认端口 2881（SQL）与 2886（RPC）；嵌入式模式直接从 path 指向的数据目录启动
嵌入式掉电恢复：确认数据目录无损后重启进程，不要删 run/ 下的元数据
同一数据目录只允许一个进程打开；报 database opened by another process 时先检查残留进程
部署遥测 UUID 位于 <base-dir>/run/telemetry.json 的 content.id，属于实例凭证，不要外发

参考

seekdb 仓库与文档：https://github.com/oceanbase/seekdb · https://docs.seekdb.ai/
Python SDK：https://github.com/oceanbase/pyseekdb