AgentField记忆系统指南：4级记忆作用域+向量搜索，无需Redis的分布式状态方案

AgentField记忆系统指南：4级记忆作用域+向量搜索，无需Redis的分布式状态方案

【免费下载链接】agentfieldBuild, run and scale AI agents like API and microservices项目地址: https://gitcode.com/gh_mirrors/ag/agentfield

AgentField 记忆系统是 AI Agent 框架 AgentField 内置的跨 Agent 持久化状态层：它提供 global / session / actor / workflow 这4 级记忆作用域（Memory Scopes），并内建向量记忆与相似度搜索（Vector Memory），底层直接用 SQLite 或 PostgreSQL 存储，无需 Redis即可实现分布式 Agent 的状态共享。

为什么 AI Agent 需要一套记忆系统

构建 Agent 应用时，一个绕不开的问题是：状态放哪里？

多轮对话的上下文、用户偏好、工作流中间结果……传统做法是 Redis 或自建 KV 存储，但你需要自己处理：

• 隔离问题：不同会话、不同用户的数据不能互相看见
• 检索问题：Agent 想"回忆"相关信息时，精确键名查询不够用，需要语义搜索
• 运维问题：多一套中间件，就多一份部署和监控成本

AgentField 的思路是把记忆做成控制平面的一等公民：所有 Agent 节点通过统一的 HTTP API 读写记忆，存储层默认用 SQLite（单机）或 PostgreSQL（生产），向量搜索也内建在同一套存储里——一套系统同时解决 KV 状态和向量检索，不需要额外的向量数据库（如 Pinecone、Milvus）。

4 级记忆作用域：一张表看懂隔离边界

AgentField 的记忆按scope（作用域）划分，每个作用域由一个请求头标识，互不干扰：

💡 注意一个关键设计：session、actor、workflow是并列的三个维度，不是嵌套关系。写入其中一个维度的值，在其他两个维度不可见；只有global是所有人都能看到的共享兜底层。

这个结构在 Python SDK 的 memory.py 中有完整的 ASCII 图示说明。

读取优先级：workflow → session → actor → global

不带 scope 参数直接读一个 key 时，AgentField 会按固定顺序逐级查找，返回第一个命中的值：

workflow → session → actor → global

这意味着内层作用域会"遮蔽"外层同名 key：workflow 里写了config，就会遮蔽 session 和 global 里同名的config。这非常实用——你可以把默认配置放 global，用户在会话里临时覆盖时写 session，工作流跑批时再写 workflow 局部值，一套 key 三处生效、互不污染。

作用域解析逻辑在控制平面处理器 resolveScope 中实现，查找顺序定义在 GetMemoryHandler。

向量记忆：内建相似度搜索，替代独立向量数据库

结构化 KV 之外，AgentField 在同一套作用域体系下提供了向量记忆：把文本、文档、摘要的 embedding 直接存入memory_vectors表，然后用top_k + filters做相似度搜索。

核心能力（实现在 vector_memory.go）：

• 存向量：POST /api/v1/memory/vector，带 key、embedding、metadata
• 相似度搜索：POST /api/v1/memory/vector/search，传query_embedding+top_k（默认 10），支持按 metadata 过滤
• 批量清理：DELETE按 key 删除，或按 namespace 前缀一次删掉整个"命名空间"的向量

存储层有两套实现，按部署形态自动选择：

一个典型 RAG 玩法（参考控制平面知识库文章 knowledgebase/content.go）：

1. 把文档切块后向量化，写入 global 或 actor 作用域的向量记忆
2. Agent 运行时把用户 query 向量化，调vector/search取 top_k
3. 命中的内容拼进 prompt——全程无需额外的向量数据库

快速上手：API 与 SDK 用法

REST API 一览

记忆端点统一挂载在/api/v1/memory/（API Key 鉴权），端点清单定义在 catalog_entries.go：

Python SDK：两行代码开始

SDK 侧对 4 级作用域做了对象化封装（源码 sdk/python/agentfield/memory.py）：

# global 作用域：共享配置 await agent.memory.global_scope.set("config", {"temperature": 0.2}) # session 作用域：本会话上下文 await agent.memory.session(session_id).set("context", {"topic": "billing"}) # actor 作用域：跨会话的用户偏好 await agent.memory.actor(actor_id).set("preferences", {"tone": "concise"}) # 不带 scope 的读取：按 workflow→session→actor→global 逐级命中 value = await agent.memory.get("config")

TypeScript SDK 有完全对等的实现，见 MemoryClient.ts。

记忆的生命周期：持久化直到显式删除

这是很多新手容易误解的一点：scope 控制的是"谁能看见"，不是"能活多久"。

• 没有任何作用域有 TTL 或自动过期
• 结束会话不会清理 session 作用域的值
• 工作流跑完不会清理 workflow 作用域的值（workflow-cleanup 只清运行记录和凭证，不碰记忆）
• 唯一的删除途径：SDK 显式delete或对应的 HTTP 端点

官方建议的准则是：用 scope 决定隔离和查找，用显式删除决定生命周期。如果一个 key 不该在会话结束后继续存在，用完就删掉。

进阶：访问控制与记忆变更事件

访问控制。开启访问控制后，每条记忆可以携带 ACL 元数据：限定必需角色（X-Agent-Roles头）、团队隔离（X-Team-ID头）、访问审计日志。强制校验逻辑在 memory_access_control.go；服务端中间件还会基于标签策略评估memory.read / memory.write / memory.delete / memory.subscribe操作，见 memory_permission.go。

记忆变更事件。每次 set/delete 都会产生一条memory_change事件（含新旧值、操作者元数据），可被订阅——多个 Agent 实例可以基于事件实现记忆缓存失效或跨节点同步，事件发布见 memory.go，SDK 侧的事件客户端为 MemoryEventClient.ts。

部署建议与延伸阅读

• 开发/单机：零配置，控制平面默认使用 SQLite，KV 记忆和向量记忆都在本地数据库里
• 生产/多节点：切换 PostgreSQL，多个 Agent 节点共享同一份记忆与向量索引
• 表结构：记忆与向量相关的建表逻辑在 028_create_config_storage.sql，向量表memory_vectors的增删查改见 vector_store_sqlite.go
• 隔离测试：想验证多租户边界，可看 memory_isolation_test.go 和 memory_invariant_test.go

小结

AgentField 记忆系统给 AI Agent 工程提供了一个"刚刚好"的状态层：

1. 4 级作用域（global / session / actor / workflow）解决隔离与覆盖问题，读取自动逐级降级
2. 向量搜索内建，与 KV 记忆共用同一套作用域和存储，替代 Redis + 独立向量数据库的组合
3. 零额外中间件：SQLite 起步，PostgreSQL 上生产，状态管理成本大幅下降

如果你的 Agent 应用正在为"状态存哪里"头疼，这套方案值得直接抄作业。

【免费下载链接】agentfieldBuild, run and scale AI agents like API and microservices项目地址: https://gitcode.com/gh_mirrors/ag/agentfield