Aegra语义存储深度指南：用pgvector向量检索构建AI Agent长期记忆

• 后端
• 人工智能
• AI Agent

Aegra 是一款自托管的开源 AI Agent 后端，它的语义存储（Semantic Store）功能基于 PostgreSQL 的 pgvector 扩展实现向量检索，让 AI Agent 能够"按含义"存取数据——这正是构建 Agent 长期记忆、RAG 知识库与个性化记忆的关键能力。本文将带你从零配置 Aegra 语义存储，掌握向量检索的完整玩法。

为什么 AI Agent 需要长期记忆

默认情况下，AI Agent 的每次运行都是"失忆"的：对话结束后，它记不住用户的偏好，也查不到上次保存的知识。

Aegra 的 Store API 为 Agent 提供了跨运行（across runs）的持久化存储，分为两层能力：

• 键值存储：开箱即用，无需任何配置，适合存用户偏好、对话摘要等结构化数据
• 语义存储：配置向量嵌入后，存储自动为数据生成 embedding，支持"按语义相似度"检索

官方语义存储指南见 docs/guides/semantic-store.mdx，完整的 Store 文档见 docs/guides/store.mdx。

三大典型应用场景

🧠对话记忆—— Agent 语义化地回忆过往交互内容，而不依赖精确关键词匹配

📚RAG 应用—— 把知识文档存入 Store，按语义相似度召回最相关的片段

🎯个性化—— 记住用户的偏好（如代码风格、界面主题），在合适时上下文式地取回

一键开启：在 aegra.json 中配置向量索引

开启语义存储只需在 aegra.json 中添加一个store.index配置段：

{ "store": { "index": { "dims": 1536, "embed": "openai:text-embedding-3-small", "fields": ["$"] } } }

三个参数分别是什么？

配置定义见 config.py。

💡字段嵌入小技巧：fields支持 JSON 路径写法。比如["metadata.title", "content.text"]表示只对标题和内容文本生成向量，检索时会更聚焦于正文语义。缺少指定字段的数据仍会被正常存储，只是不生成对应向量。

4 种主流嵌入模型怎么选

embed支持provider:model-id格式（按第一个冒号拆分 provider），官方推荐以下组合：

选定模型后，把对应的 API Key 写入.env即可（如OPENAI_API_KEY=sk-...、COHERE_API_KEY=...）。

选型建议：个人项目优先text-embedding-3-small（1536 维、成本低、效果好）；对检索精度要求更高或数据量大时可升级text-embedding-3-large；已在 AWS 生态内的团队选 Bedrock，免跨境调用。

存一次，按语义召回：写入与检索

写入一条"用户偏好"

await client.store.put_item( namespace=["user", "123", "preferences"], key="coding_style", value={ "text": "I prefer clean code with descriptive variable names" }, )

数据落库的同时，Aegra 会自动调用嵌入模型生成向量——你不需要写任何向量代码。

用自然语言"按含义"搜索

results = await client.store.search_items( namespace_prefix=["user", "123"], query="How does this user like to write code?", limit=5, )

注意：查询里没有任何与 "clean code" 重叠的关键词，但语义检索依然能命中上面那条偏好记录。这就是向量检索相对关键词匹配的质变。

Store 的 HTTP 接口实现位于 api/store.py，写入、读取、删除、搜索、列举命名空间五大操作一应俱全。

命名空间：多租户记忆隔离

命名空间（namespace）像目录路径一样组织数据：

["users", "alice", "preferences"] → Alice 的偏好 ["users", "alice", "conversations"] → Alice 的对话记忆

所有操作默认被自动限制在当前认证用户的["users", <user_id>]命名空间下，用户之间无法越权读取彼此的长期记忆。对于团队协作场景，还可通过 store.scopes 把orgs前缀映射到org_id，实现"组织级共享知识库"。

在 Graph 节点中使用 Store：让记忆真正"活"起来

在 LangGraph 图（graph）中，store参数会被自动注入到节点函数，Agent 可以在推理过程中随时读写长期记忆：

def my_node(state, *, store: BaseStore): # 读取该用户的历史偏好 items = store.search(("users", state["user_id"], "preferences")) # 记录本次查询，沉淀为新的记忆 store.put(("users", state["user_id"], "history"), key="last_query", value={"q": state["query"]}) return {"preferences": items[0].value if items else {}}

通过 API 存入的数据图内可见，图内写入的数据也可通过 API 检索——两侧完全互通。

环境准备与常见问题

数据库要求

语义存储要求 PostgreSQL 启用 pgvector 扩展，Aegra 官方 Compose 文件已默认使用推荐镜像（见 docker-compose.yml）：

postgres: image: pgvector/pgvector:pg18

启动时 Aegra 会自动建表并创建向量索引，无需手动执行 SQL。

启动验证

配置生效后，启动日志中会出现：

INFO: Semantic store enabled with embeddings: openai:text-embedding-3-small

看到这一行，说明向量检索已就绪。

常见问题速查

🔧pgvector extension not found—— 请确认 PostgreSQL 镜像为pgvector/pgvector:pg18，而非原生 postgres 镜像

🔧Invalid embedding model—— 检查embed是否符合provider:model-id格式，且对应 API Key 已写入.env

🔧Dimension mismatch——dims必须与模型输出维度精确一致，例如text-embedding-3-small输出 1536 维，配置成别的值会报错

兼容性说明

未提供store.index配置时，Aegra 保持基础键值模式运行，存量部署无需任何改动即可平滑升级。

小结

Aegra 语义存储把"向量数据库"的复杂度封装在配置之后：一次dims+embed声明，Agent 就拥有了按含义存取数据的长期记忆能力，且完全自托管、零厂商锁定。

• 后端
• 人工智能
• AI Agent