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_keyos.getenv(ACONTEXT_API_KEY), # 从环境变量读取密钥 ) # 方式二连接自托管服务 client AcontextClient( base_urlhttp://localhost:8029/api/v1, # 你的后端 API 地址 api_keysk-ac-your-root-api-bearer-token, # 自托管服务的根密钥 )接下来创建一个“学习空间”。你可以把它理解为一个独立的记忆库或知识库通常对应一个特定的智能体或一个项目。# 创建一个学习空间 space client.learning_spaces.create(nameMyPersonalAssistant) print(f学习空间创建成功ID: {space.id}) # 创建一个会话。会话代表一次连续的交互过程。 session client.sessions.create() print(f会话创建成功ID: {session.id}) # 将这个会话关联到刚才创建的学习空间告诉 Acontext这个会话里的内容请学到那个空间里去。 client.learning_spaces.learn(space.id, session_idsession.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:00201会议室。已同步至您的日历。}) # 假设这是一个“记录用户偏好”和“预约会议室”的任务智能体执行完毕后可以标记任务完成。 # Acontext 会自动检测或接收这个完成信号触发学习流程。学习过程在后台异步进行。在演示时我们可以使用一个阻塞调用来等待学习完成并查看成果。# 等待针对这个会话的学习过程完成生产环境通常不需要主动等待 client.learning_spaces.wait_for_learning(space.id, session_idsession.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_okTrue) for skill in skills: # download 方法会将文件内容保存到指定路径 client.skills.download(skill_idskill.id, pathf./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.mdAcontext 的灵魂在于你可以自定义记忆的结构。这是通过创建或修改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 智能体的关键一步。