memodb-io/Acontext · 上手攻略

仓库：memodb-io/Acontext
链接：https://github.com/memodb-io/Acontext
分类：agent（Agent 记忆层 / Skill Memory）
作者：spark
更新：2026-07-17

是什么

Acontext 是 memodb-io 开源的 "Agent Skills 形式的记忆层"——把 agent 运行中学到的经验沉淀成可读、可编辑、可跨 agent 复用的 Markdown skill 文件。它不是又一个向量数据库，而是把"记忆 = skill 文件"做成一等公民：会话消息 → 任务完成事件 → LLM 蒸馏 → Skill Agent 写文件 → 下次 agent 通过 list_skills / get_skill_file 工具按需加载。许可 Apache-2.0，stars 约 3.6k，JS/TS 为主，最近提交 2026-07-14（采集时仍在活跃）。

它的核心反命题是：当前 agent memory 多是"黑盒向量库 + 隐式 RAG"，用户既看不见也改不了。Acontext 把"agent 学到的"具象化成 git/grep 友好的 .md 文件。

解决什么问题

Agent 落地中"记忆 / 学习"的痛点：

记忆不可读——传统 vector memory 只暴露语义检索接口，业务 / 用户无法审核 agent "学到了什么"。
记忆不可移植——vector store 绑 embedding 模型 + vector DB，换 agent 框架或换 LLM 几乎要重灌。
记忆不可纠错——agent 写错了事实，进了向量库就只能删整条，没法"像改 wiki 一样"改一行。
agent 不跨框架共享经验——LangGraph 写的 agent 经验，Claude Code / OpenAI Agents SDK 没法用。

Acontext 的解法是：Skill = Memory。skill 文件是 Markdown（甚至支持 YAML frontmatter），任何能读文件的 agent 都能用；git、grep、zip 都能管。Agent 真正需要时通过 get_skill 工具拉取（progressive disclosure），不是 top-k 语义检索——更接近人脑"想到时调用相关笔记"，而非"始终塞满上下文"。

快速安装

Acontext 提供云托管版和自托管版，Python 和 TypeScript 双 SDK 同步维护。

路径 A：Acontext Cloud（最快上手）

打开 https://acontext.io，注册账号、领取免费额度。
在 onboarding 流程里拿到 API key（sk-ac-... 前缀）。
安装 SDK：

pip install acontext        # Python
npm i @acontext/acontext    # TypeScript / Node

路径 B：自托管（Docker）

通过官方 CLI 起本地服务，前置条件：Docker 已装 + 有一个 OpenAI API key（蒸馏用 LLM，默认 gpt-4.1）：

# 一行安装 CLI
curl -fsSL https://install.acontext.io | sh

mkdir acontext_server && cd acontext_server
acontext server up

CLI 会自动生成 .env 与 config.yaml，并拉起 Docker compose。启动后：

API Base：http://localhost:8029/api/v1
Dashboard：http://localhost:3000/

启动时它会要求你提供 OpenAI（或兼容）的 API key 用于 distillation LLM。

路径 C：接入 Claude Code / OpenClaw 等已有 agent

官方提供 SKILL.md，agent 自身会读取并按步骤配置：

# Claude Code
Read https://acontext.io/SKILL.md and follow the instructions

# OpenClaw
Read https://acontext.io/SKILL.md and follow the instructions

核心用法

下面用 Python SDK 演示完整闭环：创建 learning space → 启动会话 → 写入消息 → 触发学习 → 拉取 skill 文件。

1. 初始化 client

import os
from acontext import AcontextClient

# Cloud 模式
client = AcontextClient(api_key=os.getenv("ACONTEXT_API_KEY"))

# 自托管模式
client = AcontextClient(
    base_url="http://localhost:8029/api/v1",
    api_key="sk-ac-your-root-api-bearer-token",
)

2. 建 learning space + session

"learning space"是 skill 文件的容器，"session"是会话运行空间：

space = client.learning_spaces.create()
session = client.sessions.create()
client.learning_spaces.learn(space.id, session_id=session.id)

3. 写入会话消息

agent 运行过程中，把每条 user / assistant / tool 消息实时落库：

client.sessions.store_message(session.id, blob={
    "role": "user",
    "content": "你好，我叫顾宇，是 Acme 公司的产品经理。"
})
client.sessions.store_message(session.id, blob={
    "role": "assistant",
    "content": "你好顾宇，很高兴认识你！有什么可以帮你？"
})
# ... agent 继续跑 tool call 等 ...

4. 触发学习（distillation）

任务标记完成时，Acontext 会自动跑蒸馏 LLM，把对话 + 执行 trace 提炼成 skill 内容：

# 等后台蒸馏完成（demo 用，生产是异步的）
client.learning_spaces.wait_for_learning(space.id, session_id=session.id)

生产环境下这一步不需要显式调用——task complete / failed 事件触发即可，agent 自身不阻塞。

5. 拉取 skill 文件

蒸馏完成后，skill 以 Markdown 文件落地：

skills = client.learning_spaces.list_skills(space.id)

for skill in skills:
    client.skills.download(skill_id=skill.id, path=f"./skills/{skill.name}")

下载下来的就是普通 .md，可以直接 cat、grep、提交到 git、用编辑器改。

6. 在 agent 侧消费 skill

给 agent 配两个工具：list_skills 和 get_skill_file。agent 决定何时调用，按需读：

@agent.tool
def list_skills(space_id: str):
    return client.learning_spaces.list_skills(space_id)

@agent.tool
def get_skill_file(skill_id: str, path: str):
    return client.skills.read(skill_id=skill_id, path=path)

关键点：检索是工具调用 + 推理，不是 embedding top-k——这避免了"塞满上下文"的语义检索代价。

7. 用模板快速开始

CLI 自带模板，覆盖 OpenAI Agents、Claude Agent SDK、agno、smolagents 等主流框架：

acontext create my-proj --template-path "python/openai-basic"
acontext create my-proj --template-path "python/claude-agent-sdk"
acontext create my-proj --template-path "python/agno-basic"

典型适用场景

长生命周期 agent 的"经验沉淀"：客服 agent 跑三个月后能记住"张三是 VIP、偏好中文"等上下文。
跨 agent 框架共享知识：LangGraph 的经验直接给 Claude Code / AI SDK 用，无需重新 embedding。
可审计的 agent 记忆：金融 / 医疗场景里，业务 / 合规需要看 agent "为什么做出这个判断"，Markdown 文件天然可 diff。
本地优先 / 自托管：不想把对话数据上公有云的团队，本地 docker 一键起。
agent "自我修正"循环：agent 失败 → 用户标记 → 蒸馏 → 下次走对的路径。

坑与注意

需要 OpenAI（兼容）API key 做 distillation：自托管也避不开蒸馏这一步，因为 skill 提炼本质上是 LLM 任务。可换成 vLLM / TGI 自部署的兼容端点，但 README 默认 OpenAI。
wait_for_learning 是 demo 辅助：在生产链路里靠事件触发异步蒸馏，不要每次都阻塞等待。
SKILL.md schema 决定 skill 形态：Acontext 的"按什么结构写"由你的 SKILL.md 决定；如果 schema 写得模糊，蒸馏出来的 skill 文件质量也会飘。建议先用模板（acontext create），再迭代。
agent 必须能调用工具：纯 LLM 调用不行的，必须有 function calling / tool use 能力才能消费 list_skills / get_skill_file。
进度披露 vs 语义检索是设计取舍：在某些"先 recall 后回答"的场景（如大量历史 QA），纯按需拉 skill 可能漏召回；要根据任务特性权衡。
生态相对早期：和 Letta、mem0 等同类相比，2026 年还在快速迭代，API 可能在 0.x → 1.x 期间有破坏性变更，跟随 changelog。

与同类对比

项目	核心抽象	存储	检索方式	强项	弱项
Acontext	Skill = Memory（Markdown 文件）	文件 / disk	工具调用 progressive disclosure	可读、可改、跨框架、零 embedding	蒸馏需要 LLM；早期生态
mem0	记忆条目 + 分类	向量 DB + KV	语义检索 + 规则	易接入 LangChain、LlamaIndex	不可读、embedding 绑定
Letta（前 MemGPT）	分层记忆 + 工具	Postgres + 向量	agent 工具调用	长上下文 / 分层心智模型	部署 / 学习曲线重
LangMem	LangGraph 集成	向量 + KV	语义检索	和 LangChain 生态无缝	强绑定 LangGraph
Cognee	知识图谱 + 向量	多	KG + 语义	关系型查询	启动重、模型选择多

Acontext 的差异化：把"记忆"从黑盒向量挪到可读 Markdown，用 progressive disclosure（工具拉取）替代 top-k 检索，文件可 git/grep/zip，真正做到"开放、可审计、跨框架"。

一句话推荐结论

如果你想要的是"agent 学过的东西能被人读、被 git 管理、被任意框架复用"，Acontext 的 skill-as-memory 范式是目前最务实的一种落地方式；如果只是想要"自动写一条记忆"，传统向量方案更轻量。