PowerContext

让上下文跟着工作走 —— 跨越会话、跨 Agent、跨人。

PowerContext 是什么？

PowerContext 是一个面向 AI Agent 的开源上下文服务。 它把工作里值得长期保留的部分——已经确认的决定、约束、证据、进展——从某一次对话里搬出来，这样下一个会话、下一个 Agent、或者下一个接手的人，都能从当前进展继续，而不必重读全部记录。

可以把 PowerContext 理解为三层，也可以直接使用完整 Server 或把同一套契约嵌入其他应用：

层	负责什么	适合什么时候使用
Core protocol	`Source`、`Artifact`、`Trigger` 抽象契约	嵌入 PowerContext 或扩展组件
Builtin runtime	Memory、Handoff、Experience、Skill 服务，以及调度、推理和受支持的存储后端	运行标准本地 Server
Server 与 integrations	HTTP/MCP、Python Client、CLI、Dashboard 和 Agent 插件	接入 Agent 或应用

工作很少会由开始它的人或 Agent 独自完成。你把任务交给 Agent，Agent 推进一部分，之后可能由你或其他人接手。推理过程和当前状态却常常留在那段对话里。PowerContext 把它们从对话里移出来，变成可以查看、带版本号的 Artifact：

每一项内容都属于一个 Scope——一条独立的 Source 日志、一套 Memory 生命周期、一个评审收件箱和一份 Handoff 历史。Scope ID 只用于选取数据，它不证明用户身份、不授予工具访问权限，也不授权执行。

Scope
├── Source journal    # 证据：输入、文档、工作契约、任务结果
├── Memory            # atomic-memory/ARTIFACT_ID@REVISION —— 决定、约束、下一步
├── Review Inbox      # 等待评审的 Experience 与 Skill 候选
├── Handoff history   # handoff/ARTIFACT_ID@REVISION —— 跨会话的工作接续
└── Topic Memory      # 由符合条件的 Source 后台提取

下面两张 Dashboard 截图使用的是合成演示记录。

Memory —— 活得比会话更久的决定与约束

Memory 是一个带版本的 Artifact 家族，存放可以复用的决定、约束、事实、状态和下一步。条目状态为 active、 forgotten、merged 或 retired。通过 POST /v1/atomic-memory/lifecycle 遗忘一条，会把它移出主动召回，但内容和历史仍然可用、可恢复，且不会推进内容 revision。显式写入 Memory 完全不需要模型；从已捕获的 Source 中提取，才需要配置生成流水线。

"别重构老的 auth 模块 —— 移动端还在用。" 这么贵的上下文，不应该依赖有人每个会话都重讲一遍。

Handoff —— 当前状态，不是整段对话记录

Handoff 用一个四步循环记录工作接续：

工作契约 → Prepared Handoff → 确认回执 → 任务结果

handoff_current_work 抓取一个已经检查过的边界，返回一份临时的 Prepared Handoff。只有在你希望留下里程碑时，提交它才会生成持久的 Revision。接收方解析这份 Handoff 并记录确认回执；任务结果则作为 Source 证据保存最终状态与检查项。Handoff Report 会把每个选定 Scope 中最新的一份 Handoff Revision 投影出来供查看与导出——只读，且从不改写 Memory。

Experience —— 有用的做法，评审后再复用

Experience 记录一个场景、一次动作、观察到的结果，以及可复用的经验教训。它以 pending 候选的身份进入 Scope 内的评审收件箱。评审写入使用 expected_version，因此在别的写入方改动了提案之后，决策不会静默生效。通过会写入一个不可变的 Revision；驳回则记录原因。两者都是终态，并且只有已通过的当前版本参与召回——待审、被驳回和历史的 Revision 都会被排除。

Skill —— 经过评审的流程，需要显式导出

一个受管的 Skill 包含名称、发现描述、指令、校验项和血缘。评审通过不等于安装或执行：必须先显式导出某一个明确的已通过 Revision，Agent 宿主才能发现对应的宿主内副本。

运行指标提供依赖状态观察、处理进度新鲜度和执行尝试延迟；独立后台部署也可使用受保护的专用指标端点。

为什么选 PowerContext？

上下文活在对话之外。 Memory、Handoff、Experience、Skill 都是服务端 Artifact，不是某个 Agent 家目录里的文件。从 Codex 换到 Claude Code，或者把工作交给同事，工作本身跟着你走。
一切都带版本、可追溯。 每个 Artifact 都以 家族/ARTIFACT_ID@REVISION 寻址。通过替换产生的后续 Revision 不会改变 Artifact ID，读取一个精确的引用会返回那一份历史快照，即使家族主版本已经前进。
生成、评审、执行是三个分开的步骤。 模型可以提出内容，评审通过某个 Revision，导出生成宿主内副本。这三步都不会授予 Agent 执行指令的权限。各个入口目前各自暴露了什么，见接口说明。
召回是有边界的，不是整包倾倒。 PreparedContext 会按请求选择活跃的 Memory 和已通过的 Experience，并可选加入 Profile 快照和 Topic Memory，再套用一个共享的字节预算，返回 ready 内容或 empty。召回的内容是历史，不是指令权威：接收方仍然要遵循当前指令，并检查工作区的实时状态。
复用之前先评审。 Experience 和 Skill 都要经过一次评审决策，无论通过还是驳回都是终态；批准会写入不可变 Revision。启用权限控制后，批准需要 scope.review。有审核权限的 Agent 仍可批准自己的 Candidate；需要由人决定时，应使用不同身份和权限分离 Agent 提交与审核。
一个 Server，同一份契约的多个视图。 HTTP 是完整的远端应用契约。Python Client 提供带类型的访问，MCP 是面向 Agent 的精选投影，Core 协议则允许应用自行组装 Source、Artifact 和 Trigger 实现。

横向对比

以下按常见的单 Agent 或宿主本地部署方式比较；具体能力取决于各系统的部署与集成方式。

	手动翻聊天记录	对聊天记录做 RAG	宿主本地记忆文件（如 CLAUDE.md）	PowerContext
跨会话留存	手动	是	是	是
换 Agent 后仍可用	否	否	否	是
把工作交给另一个人	手动	手动	手动	Handoff，一等公民
可复用的流程	无	无	仅自然语言描述	Experience / Skill
保留历史版本	否	取决于索引	仅通过 git	不可变 Revision
复用前经过评审	不适用	否	否	评审收件箱
单轮召回有预算约束	否	部分	否	`PreparedContext` 字节预算
可以在 Agent 之外查看	否	否	是	是

效果怎么样

长对话记忆（LoCoMo；类别 1–4 的 1,540 个计分问题）：准确率 90.78%，PowerMem 为 87.79%，全量上下文重放为 52.9% —— 相对后者 +37.88 个百分点。
编码任务（SWE-bench Pro；731 个公开 v2 任务的配对项目运行，非官方提交）：开启 PowerContext 后任务解决率 86.73%，关闭时 82.35% —— +4.38 个百分点，多解出 32 题。
召回质量（LoCoMo Plus）：原生 PowerContext 对比检索后用 Jev 做候选筛选。每组模型同时用于 Memory 抽取与回答，向量模型为 qwen3.7-text-embedding（1024 维）：

模型 PowerContext PowerContext + Jev 差值

GPT-4o-mini 40.855% 49.78% +8.925 个百分点

Qwen3.7-plus 60.37% 68.947% +8.577 个百分点

GPT-4o 65.082% 69.28% +4.198 个百分点

模型	PowerContext	PowerContext + Jev	差值
GPT-4o-mini	40.855%	49.78%	+8.925 个百分点
Qwen3.7-plus	60.37%	68.947%	+8.577 个百分点
GPT-4o	65.082%	69.28%	+4.198 个百分点

评测方法、完整结果和适用边界：官网评测页。有两点我们宁愿写明而不是藏起来：上面这六组 LoCoMo Plus 分数由项目方提供，运行产物尚未公开供复核——公开的是评测工具的复现步骤，不代表这些分数本身已被公开验证。Windows 支持为 experimental。

快速开始

如果希望自己一步一步配置并启动 PowerContext，请查看手动启动文档。

PowerContext 把可长期复用的项目上下文放在单次对话之外。一次完整体验可以概括为：

Agent 输入 → Source 证据 → Memory / Topic Memory → PreparedContext → 新会话或新 Agent

PowerContext 1.4.0 包含交互式配置向导。需要 Python 3.11+、Git 和 uv；需要时 uv 可以按需提供 Python。要接入 Agent，还需要安装对应的 CLI。向导中选择“基础记忆”即可在没有模型 API 的情况下显式保存与召回；选择“完整记忆能力”则需要独立的 Generation、Embedding API 凭据。只想启动不依赖模型 API 的本地 Server 时，请参考安装与运行。支持 macOS 和 Linux；Windows 支持为 experimental。

请选择与你目标匹配的路径：

目标	选择	需要
体验显式保存与召回	基础记忆	CLI 和 Server；无需模型 API
自动处理 Source，使用 Topic Memory 或语义检索	完整记忆能力	独立的 Generation、Embedding API 凭据；仍受调度和 Scope 策略影响
用 Python 学习核心工作流	前七篇 Jupyter 教程	仓库 checkout 和 `uv`；不需要模型或 API Key

1. 安装并运行配置向导

uv tool install --force "powercontext[cli,server]==1.4.0"
mkdir -p powercontext-config && cd powercontext-config
powercontext config init --language zh --output .env
powercontext config validate --env-file .env
powercontext server run --env-file .env      # 保持这个终端不关

向导会询问存储、本机或远程使用场景、记忆能力、Dashboard/访问控制和 Agent 连接。首次体验可以使用 SQLite；只有确实需要时再选择嵌入式 seekdb，并同意依赖安装。

向导生成一个 .env 环境文件和 .env.next-steps.md。这些文件可能包含凭据，请勿提交到 Git。保持 Server 运行，在另一个终端回到 powercontext-config 目录，重新加载生成的环境文件并检查服务：

set -a
. ./.env
set +a
powercontext ready
powercontext capabilities

接着按 .env.next-steps.md 创建并绑定 Scope。使用创建请求返回的真实 scope_id；向导规划的 codex-... 标题不是 ID。切换目录不会创建隔离；Dashboard 和 Agent 要使用同一个 Server 和 Scope。然后安装相同版本的插件，再打开新 Agent 会话。完整安装流程包含 Codex、Claude Code、Dashboard 登录、SSH 隧道、HTTPS 前提及逐项验收。例如，匹配本版本的 Codex 安装命令是：

powercontext setup codex --ref powercontext-v1.4.0
powercontext doctor codex

在新 Codex 会话发送第一条消息前，打开 /hooks 检查 PowerContext Hook，并在收到提示时授予信任。 UserPromptSubmit Hook 未启用时，即使 MCP 连通，也不会自动采集输入或召回上下文。检查与恢复步骤见首次会话 Hook 信任。完成下面的首次验收后，可按能力与触发指南体验七类 Artifact、Source 和 Tag。基础记忆无需独立的 Server 模型 API；Agent 仍使用自己的模型。

2. 验收第一条端到端结果

这一步检查 PowerContext 真正有用的链路：Source 采集 → 后台处理 → 跨会话召回。在绑定了同一 Scope 的新 Agent 会话中，发送一条具体决定，例如：

我们正在设计 Aurora 验收项目。决定用 uv 管理 Python 依赖，配置文件使用 .env。
第一阶段只在一台 Linux 服务器运行，Mac 通过 SSH 隧道访问。请复述这些约束，暂时不要修改代码。

如果开启了 Dashboard，打开向导打印的地址；采集前页面为空是正常现象。然后：

确认这条输入出现在 Source 中。
等待配置的检查周期和模型处理，确认出现相关 Topic Memory。
发送一条相关更新，确认新的 Source 入库，且主题内容或修订记录反映了更新。
使用同一 Scope 开启新的 Agent 会话，要求它带引用找回 Aurora 的决定。

doctor codex 只检查安装与连接。Source 采集本身不会创建 Memory 或 Topic Memory，后台处理还要等待配置的调度和模型运行。基础记忆模式下，可以显式要求 Agent 保存一条决定，再在新会话中搜索；这不能验收自动提取。

3. 先用 Python 体验

教程需要在仓库 checkout 内运行，依赖由 uv 的依赖组提供，不在 powercontext 包内。在仓库根目录执行：

uv sync --locked --group notebooks
uv run --locked --group notebooks jupyter lab --notebook-dir=examples/jupyter

先从 01 · 让新会话用上项目约定开始，再通过 22 篇中文 Jupyter 教程与完整团队工作流亲手运行 Memory、上下文、交接、Experience、Skill 和真实 Agent。前七篇不需要模型或 API Key。

常见问题

doctor codex 只验证 Codex 集成的安装和连接，不代表自动记忆流程已通过。要验收自动记忆，需要确认真实输入进入 Source、产生 Topic、相关输入推动主题演进，并能在使用同一 Scope 的新会话中召回。
Python 依赖下载缓慢或失败时，可先为 uv 配置包索引（镜像源）再重试。
要体验自动 Memory 提取和 Topic Memory，请选择完整记忆能力并准备独立的 Generation、Embedding API 凭据；Agent 官方订阅不会自动给 PowerContext Server 提供这些凭据。选择基础记忆则可显式保存与召回，无需额外模型 API。
选择 seekdb 且缺少依赖时，会在确认后后台增量安装。
可选的召回充分性门控会按 Scope 记录每日搜索工作量和字节预算遗漏，供后续策略评估使用。记录范围与失败行为见配置说明。
Server 部署在另一台机器上时，请使用 HTTPS 或参考远程连接说明。配置向导会从参数或环境变量识别远端 HTTP 地址并要求显式确认；自动化场景使用 --allow-insecure-http。

接入你的 Agent

Codex 标为 official，其他受维护的宿主及 Python Agent 框架标为 community，Bub 标为 evaluation，仅用于评测。这些标签表示 PowerContext 集成的维护归属和用途；哪些宿主已通过资格验证、各自支持哪些功能，以能力矩阵为准。

_Codex	_{Claude Code}	_{MiniMax Code}	_{DeepSeek Harness}	_ZCode	_{Kimi Code}	_{Hermes Agent}	_{Pi Coding Agent}
_OpenClaw	_OpenCode	_WorkBuddy	_Bub	_{Pydantic AI}	_LangChain	_LangGraph