Acontext：为AI智能体构建可读可编辑的技能记忆层-深圳市維司達科技有限公司

1. 项目概述：为AI智能体构建一个可读、可编辑的技能记忆层

如果你正在构建AI智能体，并且厌倦了那些像黑盒子一样、难以调试、无法手动干预的“记忆”系统，那么Acontext就是你一直在寻找的答案。简单来说，Acontext是一个开源的“技能记忆层”，它把智能体在运行中学到的一切——无论是成功的经验、失败的教训，还是用户的偏好——都自动提炼、存储为一份份清晰可读的Markdown文件，也就是所谓的“技能文件”。

想象一下，你的智能体在帮用户订餐时，第一次搞错了用户对“微辣”的定义，导致用户不满意。传统的记忆系统可能只是在向量数据库里塞进一堆难以解读的嵌入向量。而Acontext则会自动生成一个名为user_preference_spicy_level.md的技能文件，里面用明文记录着：“用户‘Gus’定义的‘微辣’标准是：辣椒粉少于半茶匙，偏好使用小米椒而非朝天椒。” 下次智能体再为Gus服务时，可以直接读取这个文件，精准复现他的口味。这种将记忆“文件化”、“技能化”的思路，彻底改变了我们管理智能体长期经验的方式。

2. 核心理念：为什么“技能即记忆”是更优解？

2.1 传统智能体记忆的痛点

在深入Acontext之前，我们必须先理解当前智能体开发中“记忆”模块普遍存在的几个顽疾：

不透明与不可调试：大多数记忆系统依赖向量检索，将对话历史或总结文本转化为高维向量。当智能体做出一个基于“记忆”的奇怪决策时，开发者几乎无法追溯是哪个记忆片段导致了这个问题，因为你看不懂向量。
上下文污染与成本激增：为了记住更多，简单粗暴的方法是把所有历史对话都塞进上下文窗口。这很快会导致令牌数爆炸，增加API成本，并可能让关键信息淹没在冗长的上下文中。
僵化与难以演化：记忆一旦以某种格式（如固定的JSON结构或向量）存入，就很难根据新的任务类型进行结构调整或语义升级。你想从“记录用户偏好”扩展到“记录项目工作流”，可能就需要推倒重来。
框架与供应商锁定：记忆系统往往深度绑定特定的Agent框架或云服务。一旦你想迁移或尝试新的LLM，记忆数据的迁移就是一个噩梦。

Acontext提出的“技能即记忆”哲学，正是针对这些痛点的一剂解药。它的核心思想是：既然智能体的“技能”（例如，“如何格式化代码”、“如何与某API交互”）可以用人类可读的文件（如Markdown）来定义和共享，那么智能体的“记忆”（即从经验中学到的知识）为什么不能是同样的东西呢？

2.2 Acontext的四大设计原则

基于上述哲学，Acontext的架构遵循几个清晰的原则：

纯文本文件，框架无关：所有记忆都以Markdown文件形式存在。你可以用任何文本编辑器查看、用grep命令搜索、用git进行版本管理。无论是LangChain、LangGraph、Claude API还是Vercel AI SDK，只要能读文件，就能利用这些记忆。没有嵌入模型，没有专属API的捆绑。
结构由你定义：记忆的组织方式完全由你决定。你可以通过上传或编写一个“上下文技能”文件（SKILL.md）来定义记忆的schema、命名规范和文件目录结构。例如，你可以规定每个联系人一个文件（contacts/john_doe.md），或者每个项目一个文件夹（projects/project_alpha/meeting_notes.md）。
渐进式披露，而非语义搜索：智能体不是通过一个“搜索记忆”的模糊工具来获取信息。相反，它被赋予像get_skill（获取技能内容）和get_skill_file（获取技能文件）这样具体的工具。智能体需要根据当前任务进行推理，主动调用这些工具来获取它认为相关的记忆。这保证了记忆的调用是精准、有目的性的，避免了无关信息干扰。
一键导出，随处复用：整个记忆库（技能文件集合）可以打包成一个ZIP文件下载。你可以把它放到另一个智能体中使用，或者用另一个LLM来读取分析。没有数据锁定的担忧，也不需要为新的系统重新做向量化。

3. 核心工作机制：记忆如何被存储与召回？

理解Acontext如何工作，关键在于两个流程：存储（记忆如何形成）和召回（记忆如何被使用）。

3.1 存储流程：从对话到技能文件的自动化蒸馏

存储不是简单存档聊天记录，而是一个主动的“学习”过程。以下是其核心步骤的拆解：

会话消息输入：系统接收智能体与用户的完整对话流。除了文本消息，你还可以选择性地传入工具调用记录、生成的代码或文件（称为“工件”），这些为学习提供了更丰富的上下文。
任务完成/失败触发：学习不会在每句话后发生，而是在一个“任务”被标记为完成或失败时触发。这个标记可以来自智能体的主动报告（如“任务完成”），也可以由Acontext根据对话自动推断。
知识蒸馏：这是学习的核心环节。一个LLM（默认为GPT-4）会分析触发学习的那段对话和任务执行轨迹。它的目标是回答几个关键问题：这个任务成功的关键步骤是什么？哪里出了错，根本原因是什么？用户表达了哪些明确的偏好或隐含的反馈？
技能代理决策：另一个LLM（或同一LLM的不同调用）扮演“技能管家”的角色。它基于蒸馏出的知识，并参照你预先定义的SKILL.md结构，决定将这些新知识写入哪里：是更新一个现有的技能文件，还是创建一个新的？文件应该放在哪个目录？如何命名？
更新技能文件：最终，系统将蒸馏和决策的结果，以Markdown格式写入或更新到指定的技能文件中。至此，一次经验就固化为了可持久化、可读的记忆。

实操心得：定义清晰的SKILL.mdSKILL.md是你记忆系统的蓝图。一个定义良好的结构能极大提升记忆的质量和可用性。不要只定义文件位置，更要定义内容的模板。例如，一个“用户偏好”技能模板可以包含## 忌口、## 口味偏好、## 沟通风格等章节。这样，技能代理在写入时就有据可依，生成的文件格式统一，便于后续解析和使用。

3.2 召回流程：智能体驱动的精准记忆提取

记忆的召回机制与传统向量检索截然不同，它强调智能体的主动性和精确性：

工具赋能：在你的智能体工具列表中，加入Acontext提供的list_skills（列出可用技能）、get_skill（按名称获取技能内容）、get_skill_file（获取技能文件对象）等工具。
智能体推理与调用：当智能体在执行任务中判断需要某些历史信息时（例如，“我需要知道用户Gus对辣度的偏好来推荐餐厅”），它会主动调用get_skill(“user_preference_spicy_level”)。
内容注入上下文：工具调用返回对应Markdown文件的纯文本内容。这些内容被直接注入到智能体当下的上下文窗口中，作为它决策的依据。

这种方式的好处是“按需取用”，避免了全量搜索可能带来的噪声。它迫使智能体像人类一样，先思考“我需要什么知识”，再去寻找，这是一种更高级的认知架构。

4. 从零开始：Acontext的完整集成与实操指南

理论讲完，我们进入实战环节。我将带你从注册到运行第一个具备记忆能力的智能体，并分享其中的关键配置和避坑点。

4.1 环境准备与初始化

你有两种方式使用Acontext：云端托管服务和本地自托管。对于大多数开发者和快速原型验证，我推荐从云端开始，它省去了运维的麻烦。

步骤一：获取云端API密钥

访问 Acontext.io ，使用GitHub或Google账号登录。
完成一键式引导，系统会赠送免费额度，并生成一个以sk-ac开头的API密钥。妥善保存这个密钥。

步骤二：安装SDKAcontext提供了Python和TypeScript的SDK。这里以Python为例：

pip install acontext

步骤三：初始化客户端在你的智能体主程序中，初始化Acontext客户端。

import os from acontext import AcontextClient # 方式1: 使用云端服务（推荐起步） client = AcontextClient( api_key=os.getenv("ACONTEXT_API_KEY") # 建议将密钥放入环境变量 ) # 方式2: 连接自托管实例（后文会讲） # client = AcontextClient( # base_url="http://localhost:8029/api/v1", # api_key="sk-ac-your-root-api-bearer-token", # )

4.2 创建学习空间与会话

在Acontext中，学习空间是技能记忆的容器，你可以把它理解为一个“项目”或“知识库”。会话则代表一次连续的智能体交互过程，多个会话可以关联到同一个学习空间，共同为其贡献知识。

# 创建一个学习空间，用于存储本项目所有相关的技能记忆 space = client.learning_spaces.create(name="我的个人助理项目") print(f"学习空间创建成功，ID: {space.id}") # 创建一个新的会话，代表一次用户对话 session = client.sessions.create() print(f"会话创建成功，ID: {session.id}") # 将这个会话关联到刚才创建的学习空间，并开始学习模式 client.learning_spaces.learn(space.id, session_id=session.id)

关键点在于learn方法，它建立了会话与空间的学习关系，之后该会话中标记完成的任务，其经验就会沉淀到该空间中。

4.3 模拟智能体运行与记忆生成

现在，我们模拟一个智能体与用户对话并完成任务的过程。Acontext SDK提供了存储消息的方法。

# 模拟用户和智能体的对话 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": "assistant", "content": "查询完成。已找到3个符合您要求的航班，详情已发送。任务完成。"}) # 关键：标记任务完成，触发学习过程 # 你可以通过工具调用、特定消息格式或SDK方法显式标记。这里演示SDK方法。 client.sessions.report_outcome(session.id, outcome="completed", summary="成功为用户张三查询了明天下午京沪经济舱航班。")

当report_outcome被调用后，Acontext后端就会异步启动前面提到的“存储流程”：蒸馏对话、更新技能。你可以等待学习完成，然后查看成果。

# 等待该会话的学习过程完成（用于演示，生产环境是异步的） client.learning_spaces.wait_for_learning(space.id, session_id=session.id) # 列出学习空间中生成的所有技能 skills = client.learning_spaces.list_skills(space.id) for skill in skills: print(f"技能名: {skill.name}, 路径: {skill.path}") # 下载某个技能文件查看内容 if skills: skill_content = client.skills.get_content(skill_id=skills[0].id) print("技能内容预览:\n", skill_content[:500]) # 打印前500字符

你可能会看到一个名为user_profile_张三.md或task_flight_search.md的技能文件被创建，里面包含了从这次对话中提炼出的结构化信息。

注意事项：生产环境中的异步处理wait_for_learning在演示中很方便，但在真实的智能体流水线中，绝对不要同步等待学习完成。学习是一个后台任务，可能耗时几秒到几十秒。正确的做法是，智能体在报告任务结果后就直接返回响应给用户。学习过程在后台静默进行，不影响本次交互的延迟。技能会在下次及以后的交互中被用到。

4.4 为智能体装备记忆召回工具

让智能体拥有记忆的关键，是为它提供召回工具。Acontext SDK提供了与主流Agent框架集成的工具函数。

以下是一个与OpenAI Assistant API或LangChain的tool装饰器集成的示例：

from acontext import AcontextClient # 假设使用OpenAI风格的工具定义 client = AcontextClient(api_key=os.getenv("ACONTEXT_API_KEY")) space_id = "your_space_id" def get_skill_tools(): """返回一组可供LLM调用的记忆工具""" @tool def list_available_skills(query: str = None) -> str: """ 列出当前学习空间中可用的技能。可以根据查询词进行过滤。 Args: query: 可选的过滤关键词，用于在技能名和路径中搜索。 Returns: 一个格式化字符串，列出匹配的技能名称和简要描述。 """ skills = client.learning_spaces.list_skills(space_id) filtered_skills = [s for s in skills if query.lower() in s.name.lower() or query.lower() in s.path.lower()] if query else skills if not filtered_skills: return "未找到相关技能。" result = "可用的技能有：\n" for skill in filtered_skills[:10]: # 限制返回数量 result += f"- **{skill.name}** (路径: {skill.path})\n" return result @tool def get_skill_content(skill_name: str) -> str: """ 根据技能名称获取其详细的Markdown内容。 Args: skill_name: 技能的准确名称。 Returns: 该技能Markdown文件的完整内容。如果未找到，返回错误信息。 """ skills = client.learning_spaces.list_skills(space_id) target_skill = next((s for s in skills if s.name == skill_name), None) if not target_skill: return f"错误：未找到名为 '{skill_name}' 的技能。请使用 list_available_skills 工具确认名称。" try: content = client.skills.get_content(skill_id=target_skill.id) return content except Exception as e: return f"读取技能内容时出错：{str(e)}" return [list_available_skills, get_skill_content] # 在你的智能体设置中，将这些工具添加到工具列表 agent_tools = [your_other_tools] + get_skill_tools()

现在，你的智能体在思考时，就可以自主决定调用list_available_skills(“用户偏好”)来查找相关记忆，然后调用get_skill_content(“user_profile_张三”)来获取张三的航班偏好历史，从而提供更个性化的服务。

5. 高级特性与实战场景深度解析

Acontext不仅仅是一个记忆存储库，它提供了一套完整的“上下文工程”工具链，用于管理和优化智能体的工作环境。

5.1 上下文工程：压缩、总结与编辑策略

当技能记忆越来越多，直接将所有相关文件内容塞进上下文可能再次导致令牌数膨胀。Acontext的上下文工程功能允许你对技能内容进行预处理。

自动摘要：你可以为技能配置摘要策略。例如，对于一个很长的项目总结技能，系统可以自动生成一个summary字段，只包含最关键的点。智能体在list_skills时首先看到摘要，决定是否需要获取全文。
内容编辑：你可以定义规则，在技能被注入上下文前进行编辑。例如，移除Markdown中的注释块、只保留最新的5条记录、或者将表格数据转换为简短的描述性文字。
策略链：摘要和编辑策略可以组合使用。这让你能精细控制进入智能体上下文的记忆信息的密度和格式，在信息量和成本之间取得平衡。

5.2 磁盘与沙箱：赋予智能体持久化与安全执行能力

这是Acontext区别于纯记忆库的杀手级特性。

虚拟磁盘：Acontext为每个会话或学习空间提供了一个虚拟的、持久化的文件系统。你的智能体可以通过工具（write_file,read_file,list_directory）像在真实服务器上一样操作文件。这对于需要跨对话保存中间结果（如生成的代码、下载的数据、用户上传的图片）的场景至关重要。
安全沙箱：更强大的是，它提供了一个隔离的代码执行环境（沙箱）。智能体可以通过工具在沙箱中安全地执行Bash命令、运行Python脚本等。
技能挂载：最精妙的设计在于，你可以将学习空间中的技能文件挂载到沙箱的特定路径。这意味着，智能体在沙箱中运行的代码，可以直接读取到它之前学到的“记忆”（技能文件）。例如，一个编程助手智能体，可以将“如何配置某项目”的技能挂载到沙箱的/knowledge目录，然后在沙箱的安装脚本中直接引用/knowledge/project_setup_guide.md里的步骤。

# 示例：在沙箱中挂载技能并执行命令 from acontext.tools import bash_tools # 创建一个沙箱 sandbox = client.sandboxes.create() # 将学习空间的技能挂载到沙箱的 /mnt/skills 目录 client.sandboxes.mount_skills(sandbox.id, space_id=space.id, mount_path="/mnt/skills") # 在沙箱中执行命令，读取挂载的技能 result = bash_tools.run_command(sandbox.id, "cat /mnt/skills/user_profile_张三.md | head -20") print(result.stdout)

这个组合实现了“记忆”与“行动”的无缝衔接，智能体不仅能“知道”，还能基于所知去“执行”，并且执行环境是安全隔离的。

5.3 自托管部署指南

对于数据敏感或需要深度定制的团队，自托管是更好的选择。Acontext提供了CLI工具和一键部署脚本。

前置条件：确保服务器已安装Docker和Docker Compose，并准备一个有效的OpenAI API密钥（或其他兼容的LLM API）。

# 1. 安装 acontext-cli curl -fsSL https://install.acontext.io | sh # 2. 创建并进入部署目录 mkdir acontext_server && cd acontext_server # 3. 启动服务（这会在后台拉取镜像并启动所有组件） acontext server up

执行acontext server up后，CLI会引导你配置.env文件（设置API密钥等）和config.yaml。默认使用gpt-4作为蒸馏和技能代理的LLM，你可以在配置中修改。

服务启动后，你会获得两个关键地址：

API服务：http://localhost:8029/api/v1(你的SDK需要连接这里)
管理面板：http://localhost:3000/(用于可视化查看学习空间、技能和会话)

避坑指南：自托管网络与配置
LLM可用性：确保你的自托管服务器能稳定访问你所配置的LLM API（如OpenAI）。网络波动会导致学习过程失败。
资源规划：Acontext后端依赖PostgreSQL、Redis、RabbitMQ等组件。对于生产环境，建议为PostgreSQL配置持久化存储卷，并监控Redis的内存使用。
API密钥管理：自托管版的api_key是一个固定的根令牌，在初始配置时生成。务必像保护数据库密码一样保护它。在生产中，应考虑通过反向代理添加额外的认证层。

6. 常见问题与故障排查实录

在实际集成和开发过程中，我遇到并总结了一些典型问题及其解决方案。

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

症状：对话进行了，任务也报告完成了，但在学习空间中查不到新技能。
排查步骤：
1. 检查任务报告：确认report_outcome被正确调用，且outcome参数是”completed”或”failed”。只有这两个状态会触发学习。”in_progress”不会。
2. 检查会话关联：确认执行learn方法时，传入的session.id和space.id正确无误，并且是在对话开始前或开始时关联的。
3. 查看后台日志：如果是自托管，查看Acontext核心服务容器的日志docker logs acontext-core-1。常见的错误包括LLM API调用超时、额度不足、或技能代理在写入时因SKILL.md结构定义不明确而困惑。
4. 检查SKILL.md：确保你的学习空间已上传或定义了一个有效的SKILL.md文件。这是技能写入的路线图。没有它，系统可能不知道如何存储记忆。

6.2 技能内容质量不佳或提炼不准

症状：生成的技能文件内容空洞、重复，或者提炼出的关键信息有误。
优化方案：
1. 丰富输入上下文：在store_message时，不仅存储对话文本，也把重要的工具调用输入输出、生成的工件（如图表、代码片段）作为元数据传入。更多的上下文有助于LLM做出更准确的判断。
2. 优化任务总结：在调用report_outcome时，提供一个清晰、准确的summary参数。这个总结会作为学习过程的重要提示，引导LLM关注正确的部分。例如，与其写“完成了对话”，不如写“成功预订了周一上午10点飞往纽约的航班，并记录了用户偏好靠窗座位”。
3. 定制蒸馏提示词：对于自托管用户，可以修改Acontext后端中负责知识蒸馏的LLM提示词模板，使其更贴合你的领域。例如，对于客服场景，可以强调提炼用户情绪和问题解决方案。

6.3 智能体不调用记忆工具

症状：工具已经提供，但智能体在后续对话中从不主动调用get_skill。
解决方案：
1. 优化工具描述：仔细编写工具函数的docstring。LLM根据描述决定是否调用。确保描述清晰说明了工具的用途、何时使用、以及输入参数的准确含义。例如，在get_skill_content的描述中强调“当需要获取关于特定用户或任务的已知历史信息时使用此工具”。
2. 在系统提示中引导：在给智能体的系统指令中，明确告知它拥有一个可查询的记忆库，并举例说明在什么场景下应该去查询。例如：“你拥有一个记忆库，记录了过往与用户交互的总结。在用户提及之前讨论过的话题时，你可以尝试查询相关记忆以获得更准确的上下文。”
3. 微调与少样本示例：对于高级应用，可以在对话的少样本示例（few-shot examples）中，展示一个先查询记忆再回答的完整流程，让LLM学会这种模式。

6.4 自托管服务性能与稳定性问题

症状：服务响应慢，或偶尔出现连接错误。
排查与调优：
1. 数据库连接池：检查PostgreSQL的连接数配置。在高并发下，默认配置可能不足。调整config.yaml中数据库连接池相关参数。
2. 异步任务队列：学习是CPU/IO密集型任务，通过RabbitMQ分发。确保有足够的工作者（Worker）进程来处理队列。在docker-compose.yml中增加acontext-worker服务的实例数量。
3. LLM调用超时：蒸馏过程涉及多次LLM调用。如果网络延迟高或LLM响应慢，可能导致整体学习超时。在配置文件中适当增加LLM调用的超时时间阈值。
4. 资源监控：使用docker stats或监控工具，确保服务器有足够的CPU、内存和磁盘I/O。Redis内存不足是常见性能瓶颈。

7. 架构选型与集成模式探讨

将Acontext集成到你的智能体系统中，有几种不同的模式，适合不同的场景和阶段。

7.1 轻量级集成：作为外部记忆服务

这是最简单的模式。你的智能体主程序（可能是用LangChain、LlamaIndex或原生OpenAI SDK构建的）独立运行，仅在需要存储或读取记忆时，通过Acontext的REST API或SDK进行交互。

优点：解耦彻底，不影响现有架构。可以快速为现有智能体添加记忆能力。
缺点：记忆逻辑与业务逻辑分离，需要手动管理会话和任务的对应关系。
适用场景：快速验证记忆功能的价值；为已有成熟系统添加记忆模块。

7.2 深度集成：使用Acontext提供的Agent框架模板

Acontext官方提供了与主流框架深度集成的模板，例如python/openai-agent-basic、python/agno-basic。这些模板通常已经封装好了会话管理、消息存储、自动触发学习、工具集成等逻辑。

优点：开箱即用，最佳实践内嵌。你只需要关注核心的Agent逻辑（如提示词、工具定义）。
缺点：框架绑定程度较高。
适用场景：启动新项目；希望遵循Acontext推荐的最佳实践快速搭建。

7.3 混合模式：核心记忆+Acontext高级功能

你可以只采用Acontext最核心的“技能记忆”生成和存储功能，而自己实现召回逻辑。或者，反过来，利用Acontext强大的沙箱和磁盘工具，但用自己的方式管理记忆（例如，将生成的技能文件存储在自己的向量数据库中）。

优点：灵活性最高，可以取长补短。
缺点：需要更多的开发工作量，并自行处理兼容性问题。
适用场景：有非常特定的架构需求；只想使用Acontext的某一部分特性。

我个人在实际项目中的体会是，对于大多数从零开始的智能体项目，直接从官方模板起步是最有效率的选择。它帮你规避了初期集成的大量细节陷阱。当项目发展到一定阶段，对记忆和工具有了更独特的需求时，再基于模板进行定制化改造，这样路径最为平滑。Acontext将记忆具象化为可操作文件的设计，第一次使用时可能觉得需要转变思路，但一旦习惯，你会发现它带来的透明度、可控性和灵活性，是那些封闭的记忆黑盒系统无法比拟的。它真正把记忆的掌控权交还给了开发者和智能体本身。