当前位置：首页 > news >正文

Acontext：AI智能体技能记忆层的透明化设计与工程实践

news 2026/5/10 5:53:10

1. 项目概述：Acontext，一个为AI智能体设计的技能记忆层

如果你正在构建AI智能体，尤其是那些需要处理复杂、长期任务的智能体，那么“记忆”问题很可能已经让你头疼不已。传统的记忆方案，无论是简单的对话历史堆叠，还是基于向量数据库的语义检索，都存在一个核心痛点：记忆本身是“黑盒”。你很难确切知道智能体记住了什么、为什么记住、以及这些记忆是如何被调用的。调试起来像在迷雾中摸索，用户也无法直观地查看或修正智能体的“知识库”。

Acontext 正是为了解决这个问题而生的。它提出了一个非常直观且强大的理念：将智能体的记忆，以“技能文件”的形式来构建和管理。简单来说，Acontext 是一个开源的技能记忆层，它能够自动从智能体的运行会话中捕获“学习成果”——比如它成功完成了什么任务、用户有什么偏好、上次在哪里踩了坑——并将这些成果整理、提炼成一份份可读、可编辑、可分享的 Markdown 文件。这些文件，就是智能体的“技能”。

这个想法的精妙之处在于，它把记忆从一种抽象、难以捉摸的内部状态，变成了具象、结构化的外部资产。你可以像管理代码一样，用 Git 来版本化管理这些技能文件；可以用任何文本编辑器打开查看和修改；可以轻松地将一个智能体学到的技能，打包成一个 ZIP 文件，直接“安装”给另一个完全不同的智能体或 LLM 框架使用。记忆不再是锁在特定框架或数据库里的“私产”，而是变成了可流通、可组合的“公共知识”。

2. 核心理念与架构设计解析

2.1 核心理念：技能即记忆，记忆即技能

Acontext 的哲学建立在几个关键原则上，这些原则共同定义了它与众不同的设计思路。

2.1.1 以文件为中心的透明化

Acontext 坚决反对“黑盒记忆”。所有记忆都以纯文本 Markdown 文件的形式存在。这意味着：

可读性：任何开发者、甚至最终用户，都可以直接打开文件，理解智能体到底“知道”了什么。是记住了用户的姓名“Gus”，还是学会了“每周五下午三点生成周报”这个工作流，一目了然。
可编辑性：如果你发现智能体记错了，或者想手动补充一些重要信息，直接编辑文件即可。无需通过复杂的 API 或管理界面。
框架无绑定：这份 Markdown 文件可以被 LangGraph、Claude API、Vercel AI SDK 或任何能读取文件的系统使用。记忆的载体是通用的文本，而非某个专有格式或嵌入向量，彻底避免了供应商锁定。

2.1.2 用户定义结构，系统自动填充

记忆应该怎么组织？是按联系人、按项目、还是按任务类型？Acontext 认为这应该由你，也就是智能体的设计者来决定。你通过上传或编写一个SKILL.md文件来定义记忆的“模式”。这个文件就像一个模板或蓝图，告诉 Acontext：“我希望记忆按这种结构来存储”。例如，你可以定义一个“联系人”技能模板，那么 Acontext 在后续学习时，就会自动为每个联系人创建或更新一个对应的 Markdown 文件。系统负责从原始对话中提取信息并填充到正确的文件位置，而你掌控着信息的最终形态和组织逻辑。

2.1.3 渐进式披露，而非语义搜索

这是 Acontext 在记忆召回机制上的一个关键创新。它摒弃了传统的“输入查询 -> 语义搜索返回 top-K 相关片段”的模式。相反，它为智能体提供了诸如get_skill、get_skill_file这样的工具。当智能体在任务执行过程中，认为自己需要某段记忆时，它会主动、有目的地调用这些工具来获取特定文件或内容。

这种“工具调用式召回”有几个巨大优势：

推理在环：智能体需要先“思考”自己需要什么，这本身就是一种对上下文的利用和推理过程，比单纯的语义匹配更精准。
减少幻觉：智能体获取的是完整的、结构化的文件内容，而不是可能断章取义的文本片段，信息更完整，被误导的风险更低。
可控性强：你可以通过设计工具的使用逻辑和权限，精确控制智能体能访问哪些记忆，何时访问，实现了记忆访问的精细化管理。

2.2 系统架构与工作流程

Acontext 的架构清晰地区分了客户端、后端核心和基础设施，确保了系统的可扩展性和灵活性。

2.2.1 存储流程：会话如何转化为技能

记忆的生成是一个自动化的提炼过程，可以概括为以下五个步骤：

会话消息输入：智能体与用户（或环境）的完整对话流，包括用户消息、助手回复、工具调用记录以及产生的“工件”（如生成的代码、文件），作为原始的“学习材料”被送入系统。
任务完成/失败触发：系统需要知道从哪段对话中学习。Acontext 会监测任务的明确完成信号（如智能体报告“任务完成”）或失败信号，也可能自动从对话流中推断出任务的边界。这个“任务完结”的时刻，就是触发学习过程的扳机。
提炼：这是核心的“学习”环节。一个 LLM（默认为 GPT-4）会分析整个任务相关的对话和执行轨迹。它的目标是进行“事后复盘”：这次任务中，哪些操作是成功的、值得保留的“最佳实践”？哪些地方失败了、原因是什么？用户表达了哪些明确的偏好或约束？LLM 将这些洞察从具体的对话实例中抽象出来。
技能代理决策：另一个 LLM（或同一 LLM 的不同步骤）扮演“知识管理员”的角色。它根据上一步提炼出的洞察，结合你预先定义的SKILL.md结构，决定这些新知识应该归属到哪里：是更新一个现有的技能文件（例如，更新“用户Gus”的联系信息），还是创建一个全新的技能文件（例如，新建一个“处理退款请求”的工作流程）？
更新技能：最后，系统按照决策，将结构化的知识写入到对应的 Markdown 技能文件中。至此，一次从“经历”到“记忆”的转化就完成了。

2.2.2 技术栈与部署

Acontext 后端采用 Python (FastAPI) 构建，提供了完善的 RESTful API。数据持久化使用 PostgreSQL，文件存储支持 S3 兼容的对象存储，消息队列使用 RabbitMQ 来处理异步的学习任务，Redis 用于缓存和会话状态管理。这种选型兼顾了可靠性、性能和云原生部署的便利性。

对于开发者，最方便的是它提供了云服务和自托管两种选择。云服务（Acontext.io）提供开箱即用的体验和免费额度，适合快速启动和原型验证。自托管方案则通过一个简单的acontext-cli工具，配合 Docker，可以在几分钟内将全套后端（包括数据库、Redis 等）在本地或私有服务器上启动起来，满足了企业对数据隐私和定制化的需求。

3. 核心功能与实操要点

3.1 技能记忆的实际操作

让我们通过一个具体的 Python 示例，看看如何将 Acontext 集成到你的智能体工作流中。假设我们正在构建一个个人助理智能体。

首先，安装 SDK 并初始化客户端。如果你使用云服务，需要去 Acontext.io 获取 API Key；如果自托管，则指向你的本地服务器地址。

import os from acontext import AcontextClient # 方式一：使用云端服务 client = AcontextClient( api_key=os.getenv("ACONTEXT_API_KEY"), # 从环境变量读取密钥 ) # 方式二：连接自托管服务 client = AcontextClient( base_url="http://localhost:8029/api/v1", # 你的后端 API 地址 api_key="sk-ac-your-root-api-bearer-token", # 自托管服务的根密钥 )

接下来，创建一个“学习空间”。你可以把它理解为一个独立的记忆库或知识库，通常对应一个特定的智能体或一个项目。

# 创建一个学习空间 space = client.learning_spaces.create(name="MyPersonalAssistant") print(f"学习空间创建成功，ID: {space.id}") # 创建一个会话。会话代表一次连续的交互过程。 session = client.sessions.create() print(f"会话创建成功，ID: {session.id}") # 将这个会话关联到刚才创建的学习空间，告诉 Acontext：这个会话里的内容，请学到那个空间里去。 client.learning_spaces.learn(space.id, session_id=session.id)

现在，模拟你的智能体运行。每当智能体产生一轮对话（包括用户输入和助手回复），你就将这些消息存储到会话中。

# 模拟用户和智能体的对话 client.sessions.store_message(session.id, blob={"role": "user", "content": "我的名字叫张三，我喜欢喝黑咖啡，不加糖。"}) client.sessions.store_message(session.id, blob={"role": "assistant", "content": "好的，张三。已记录您的咖啡偏好：黑咖啡，无糖。今天有什么可以帮您？"}) client.sessions.store_message(session.id, blob={"role": "user", "content": "请帮我预约明天下午两点的会议室。"}) client.sessions.store_message(session.id, blob={"role": "assistant", "content": "已完成预约。明天（3月15日）下午14:00，201会议室。已同步至您的日历。"}) # 假设这是一个“记录用户偏好”和“预约会议室”的任务，智能体执行完毕后，可以标记任务完成。 # Acontext 会自动检测或接收这个完成信号，触发学习流程。

学习过程在后台异步进行。在演示时，我们可以使用一个阻塞调用来等待学习完成，并查看成果。

# 等待针对这个会话的学习过程完成（生产环境通常不需要主动等待） client.learning_spaces.wait_for_learning(space.id, session_id=session.id) # 列出这个学习空间里所有已学会的技能（即生成的Markdown文件） skills = client.learning_spaces.list_skills(space.id) print(f"共学习了 {len(skills)} 个技能：") for skill in skills: print(f" - {skill.name}") # 将这些技能文件下载到本地查看 import os os.makedirs("./my_assistant_skills", exist_ok=True) for skill in skills: # download 方法会将文件内容保存到指定路径 client.skills.download(skill_id=skill.id, path=f"./my_assistant_skills/{skill.name}.md")

执行完上述代码后，你会在./my_assistant_skills目录下找到生成的.md文件。打开它们，你可能会看到类似这样的内容：

user_preferences_张三.md

# 用户偏好：张三 **基本信息** - 姓名： 张三 - 记录时间： 2024-03-14T10:30:00Z **饮食偏好** - 咖啡： 黑咖啡，不加糖。

meeting_room_booking_procedure.md

# 会议室预订流程 **成功案例记录** - 时间： 2024-03-15 14:00 - 地点： 201会议室 - 用户： 张三 - 操作总结： 接收到用户明确的日期、时间、资源（会议室）请求后，执行预订操作，并确认已同步至用户日历。 - 关键步骤： 1. 确认用户需求（时间、资源）。 2. 检查资源可用性。 3. 执行预订系统调用。 4. 向用户发送确认信息，并告知已同步日历。

实操心得：在实际集成中，wait_for_learning这个阻塞调用主要用于演示和调试。在生产环境中，你应该让智能体正常结束任务，Acontext 的后台服务会自动处理学习任务。你的主程序无需等待，从而实现异步、非阻塞的记忆形成。确保你的消息存储是完整的，特别是包含工具调用和结果的消息，这能为提炼环节提供更丰富的上下文。

3.2 上下文工程与磁盘工具

Acontext 的功能远不止于被动地记录技能。它还提供了主动管理上下文和文件系统的强大工具，这对于构建复杂的、能处理多步骤任务的智能体至关重要。

3.2.1 上下文工程

当对话历史很长时，如何有效地将关键信息传递给 LLM 是一个挑战。Acontext 的上下文工程功能允许你对会话历史进行“压缩”和“编辑”。

总结：可以自动将一段冗长的对话总结成简洁的要点，作为后续对话的上下文，节省 Token 并聚焦重点。
策略编辑：你可以定义规则，例如“只保留最近10轮对话”或“自动移除所有系统提示词”，动态地塑造送入模型的上下文窗口。这让你能精细控制智能体“记得”多远的过去，以及以何种形式记住。

3.2.2 虚拟磁盘与沙箱

这是 Acontext 另一个极具特色的功能，它让智能体拥有了一个持久化的、可编程的“工作空间”。

磁盘工具：为智能体提供一个虚拟的文件系统。智能体可以通过工具（read_file,write_file,list_directory等）在这个磁盘上创建、读取、修改文件。这个磁盘是持久化的，意味着即使智能体会话结束，下次启动时，文件依然存在。这对于需要跨会话维护状态（如一个长期编写的代码项目、一个不断更新的知识库）的应用场景是革命性的。
沙箱工具：光有文件系统还不够，智能体还需要能运行代码来验证想法、处理数据。Acontext 的沙箱提供了一个安全的隔离环境，智能体可以在其中执行 Bash 命令或 Python 脚本，并获取结果。更酷的是，技能文件可以被挂载到沙箱中。这意味着智能体在沙箱里执行代码时，可以直接读取或引用之前学到的技能文件（Markdown格式），实现“记忆”与“行动”的无缝结合。

例如，一个学习了“数据清洗流程”技能的智能体，在沙箱中处理新数据集时，可以直接挂载该技能文件作为参考指南来执行操作。

# 伪代码示例：智能体通过工具调用，在沙箱中运行命令并挂载技能 # 智能体决定调用沙箱工具 tool_call: execute_in_sandbox({ "command": "python process_data.py", "mount_skills": ["data_cleaning_procedure.md"] # 挂载名为 data_cleaning_procedure.md 的技能文件 }) # 沙箱环境会将指定的技能文件放置在可访问的路径下，process_data.py 脚本可以读取它。

4. 进阶应用与项目模板

4.1 使用 Acontext CLI 快速启动项目

为了降低上手门槛，Acontext 提供了功能强大的命令行工具acontext-cli。它不仅是自托管后端的管理工具，更是项目脚手架生成器。

首先，安装 CLI 工具：

# 使用安装脚本（macOS/Linux） curl -fsSL https://install.acontext.io | sh # 安装后，可以使用 `acontext` 命令

对于想要快速体验完整工作流的开发者，最实用的功能是使用模板创建项目：

# 创建一个基于 OpenAI Agent SDK 的模板项目 acontext create my-ai-assistant --template-path "python/openai-agent-basic" cd my-ai-assistant

这个命令会创建一个新的目录my-ai-assistant，里面已经包含了：

配置好的 Acontext 客户端初始化代码。
一个简单的基于 OpenAI 的智能体循环示例。
集成了消息存储、学习空间创建等样板代码。
相关的依赖文件（如requirements.txt）。

你可以立即运行它，看到一个已经连接了 Acontext 记忆层的智能体雏形。这比从零开始编写集成代码要快得多，也避免了配置错误。

4.2 模板详解与选择指南

Acontext 社区维护了多个针对不同框架和场景的模板，理解它们的特点能帮你快速选对起点。

4.2.1 Python 生态模板

python/openai-agent-basic: 最基础的模板，使用 OpenAI 的官方 SDK 构建智能体，集成 Acontext 进行记忆存储。适合入门和简单任务。
python/openai-agent-artifacts: 在基础模板上，增加了对“工件”的支持。智能体可以生成图像、代码文件等，并将其作为会话的一部分存储，Acontext 能将这些工件也关联到技能学习中。
python/claude-agent-sdk: 专为 Anthropic Claude API 设计，使用了 Claude 官方的 Agent SDK 和ClaudeAgentStorage。如果你偏好 Claude 模型，这是最佳起点。
python/agno-basic: 集成 Agno 框架。Agno 是一个新兴的、声明式的智能体框架，此模板展示了如何在声明式范式中使用 Acontext。
python/smolagents-basic: 基于 Hugging Face 的 SmolAgents 库。这个库以轻量、可解释性强著称，适合研究和小型实验。
python/interactive-agent-skill:高级模板，展示了交互式沙箱与可挂载技能的完整结合。智能体可以在沙箱中运行代码，并动态挂载之前学到的技能文件作为参考，非常适合构建需要复杂工具使用和知识引用的自主智能体。

4.2.2 TypeScript 生态模板

typescript/vercel-ai-basic: 基于 Vercel AI SDK，这是构建 Next.js 等全栈 AI 应用的流行选择。模板展示了在前端/全栈项目中集成 Acontext 记忆。
typescript/claude-agent-sdk: 与 Python 版对应，是 Claude Agent SDK 的 TypeScript 版本模板。
typescript/interactive-agent-skill: TypeScript 版本的交互式沙箱与技能挂载示例。

选择建议：如果你是初学者，从python/openai-agent-basic或typescript/vercel-ai-basic开始是最稳妥的。它们依赖的框架最流行，文档和社区资源也最丰富。如果你已经有特定的框架偏好（如 LangChain、Claude SDK），直接选择对应的模板。对于想探索最前沿“记忆-行动”循环的开发者，interactive-agent-skill模板提供了绝佳的范例。

4.3 自定义技能结构：编写你的 SKILL.md

Acontext 的灵魂在于你可以自定义记忆的结构。这是通过创建或修改SKILL.md文件实现的。这个文件本质上是一个“技能模板”，它用自然语言和简单的结构指示告诉 Acontext 如何组织信息。

假设你在构建一个客户服务智能体，希望按“客户”和“常见问题”来组织记忆。你可以创建一个如下的SKILL.md文件：

# 客户服务智能体技能结构指南 本文件定义了本智能体记忆（技能）的组织方式。请根据以下结构创建和更新技能文件。 ## 客户档案 每个独立的客户应拥有一个单独的技能文件。 - **文件名格式**: `customer_{客户姓名拼音或ID}.md` - **文件内容结构**:

客户档案：{客户全名}

基础信息

客户ID: {系统ID}
创建日期: {日期}
主要联系人: {姓名}

交互历史与偏好

首次接触渠道: {如：官网聊天、电话}
已购买产品: {产品A, 产品B}
已知偏好: {例如：偏好邮件沟通、关注售后支持}
重要历史事件: {例如：曾在2023年11月投诉过物流问题，已解决}

备注{其他需要记录的信息}

## 常见问题解决方案 针对重复出现的技术或业务问题，总结标准化解决方案。 - **文件名格式**: `solution_{问题关键词}.md` - **文件内容结构**:

问题：{简要描述问题}

适用场景{在什么情况下会遇到此问题}

根本原因{导致问题的常见原因分析}

解决步骤

{第一步操作}
{第二步操作}
{...}

验证方法{如何确认问题已解决}

关联知识库链接{如有，指向内部知识库文章}

当你将这个SKILL.md文件上传或关联到你的学习空间后，Acontext 的“技能代理”在学习和决策时，就会参考这个结构。例如，当从一次成功的客户问题解决会话中学习时，它可能会同时更新对应的customer_xxx.md文件（添加一条“已解决某问题”的记录），并创建或更新一个solution_网络连接超时.md文件。

注意事项：编写SKILL.md时，结构要清晰，但也不要过于复杂。Acontext 的 LLM 需要能理解你的意图。多用示例和明确的字段描述。一个好的实践是，先用你期望的最终 Markdown 文件样子作为示例写在指南里，这样能最大程度减少歧义。

5. 常见问题与排查技巧实录

在实际集成和使用 Acontext 的过程中，你可能会遇到一些典型问题。以下是我在开发和测试中积累的一些排查经验和技巧。

5.1 学习过程未触发或技能未生成

问题现象：消息已经存储到会话中，但调用list_skills返回为空，或者等待后依然没有技能文件生成。

排查步骤：

检查任务完成信号：Acontext 默认在会话任务标记为“完成”或“失败”时触发学习。请确认你的智能体流程是否正确调用了相应的状态更新接口（例如client.sessions.report_outcome），或者 Acontext 是否能从你的消息流中自动推断出任务边界。查看后台日志是确认触发条件是否满足的最佳方式。
验证消息格式：确保通过store_message存储的消息blob格式正确。它应该是一个包含role(如user,assistant,system,tool) 和content的字典。如果消息中包含工具调用，确保role为tool，并且content是工具执行的结果。不完整的工具调用链会影响提炼环节的分析。
查看学习空间关联：确认你调用wait_for_learning或查询技能列表时，使用的space.id和session.id正是你之前关联的那一对。一个常见的错误是创建了新的会话或空间，却用旧的 ID 去查询。
检查自托管后端状态：如果是自托管，确保后端服务（特别是处理异步学习任务的工作队列）正常运行。使用docker-compose logs worker（具体容器名可能不同）查看工作进程的日志，看是否有错误信息，如 LLM API 调用失败、权限错误等。
审视 SKILL.md 结构：如果技能代理无法理解你定义的SKILL.md结构，它可能无法做出“写入何处”的决策，导致学习中断。尝试简化你的SKILL.md，或者提供一个更清晰的示例。

5.2 技能文件内容质量不佳

问题现象：技能文件生成了，但内容杂乱、冗余，或者没有提取到关键信息。

优化方向：

丰富会话上下文：提炼环节的 LLM 依赖你提供的会话消息。确保消息流包含了足够多的“思考过程”和“结果”。例如，如果智能体进行了一系列工具调用来查询数据库，最好将这些工具调用（输入和输出）也作为消息存储进去，而不仅仅是最终给用户的总结。更丰富的上下文能让 LLM 更好地进行复盘。
提供明确的用户反馈：在对话中，用户的明确肯定（“做得对！”）或纠正（“不对，应该是X”）是极强的学习信号。确保这些反馈信息被包含在消息流中。
调整提炼模型：默认使用 GPT-4 进行提炼，效果通常很好。但如果你的任务领域非常专业，可以尝试在配置中切换到更新或更专业的模型（如gpt-4-turbo-preview），或者为提炼环节提供更详细的系统提示词（如果 Acontext 配置允许）。
手动编辑与迭代：记忆学习是一个迭代过程。不要期望第一次就完美。打开生成的不太理想的技能文件，直接手动修改它。一个被手动修正过的、结构良好的技能文件，会在后续作为示例，引导 Acontext 产出更高质量的新技能。这就是“教”AI 如何学习。

5.3 沙箱或磁盘工具执行失败

问题现象：智能体调用沙箱执行命令或磁盘读写工具时超时或返回错误。

排查技巧：

权限与资源限制：检查自托管部署时，Docker 容器的资源限制（CPU、内存）以及沙箱的运行时限制（执行时间、输出大小）。复杂的命令或脚本可能因资源不足而失败。
网络隔离：沙箱环境通常是高度隔离的，可能无法访问外部网络。如果你的命令需要下载依赖（如pip install）或访问外部 API，需要在沙箱配置中明确允许，或者预先在沙箱镜像中安装好所需依赖。
挂载路径问题：使用mount_skills参数时，确保指定的技能文件名确实存在于当前学习空间中。在沙箱内部，技能文件会被挂载到一个特定路径（如/mnt/skills/），你的脚本需要知道这个路径才能读取文件。查看相关模板或文档，了解具体的挂载点位置。
命令安全性：沙箱会过滤危险命令。如果你尝试执行rm -rf /或尝试访问宿主机文件系统，会被阻止。确保你的智能体生成的命令是合理且安全的。

5.4 性能与成本考量

高频会话下的建议：

异步处理是核心：务必遵循异步模式。存储消息后立即返回，不要等待学习完成。Acontext 的后台队列会处理学习任务，避免阻塞主智能体流程。
批量操作：如果一次性需要存储大量历史消息，考虑使用批量存储接口（如果 SDK 提供），以减少 HTTP 请求开销。
技能文件去重：随着时间推移，同一个技能文件可能被多次更新。Acontext 会管理版本，但你也需要定期审视技能库，合并过于碎片化的技能，或者归档不再相关的旧技能，以保持记忆库的整洁和高效。
LLM 调用成本：提炼和技能代理决策都需要调用 LLM（主要是 GPT-4）。对于对话量巨大的应用，这会是一笔成本。你可以通过以下方式优化：
- 调整学习触发频率：不必每个会话都学习，可以积累多个相似会话后批量学习一次。
- 使用更经济的模型：在配置中，对于不那么复杂的提炼任务，可以尝试使用gpt-3.5-turbo等成本更低的模型。
- 精细化 SKILL.md：一个清晰、明确的SKILL.md能减少技能代理决策时的困惑，可能减少所需的 Token 数量。

集成 Acontext 的本质是为你的智能体增加了一个持续学习和知识外化的循环。初期需要一些调试来适应其工作模式，尤其是定义好技能结构。一旦跑通，你会发现智能体变得真正“可教”和“可积累”，其能力的成长曲线将变得更加陡峭和可控。这个从“失忆型对话”到“有记忆、能进化”的转变，是构建下一代实用 AI 智能体的关键一步。

查看全文

http://www.jsqmd.com/news/787605/