上下文中枢 oceanbase/powercontext

PowerContext

上下文跟着工作走 —— 跨会话、跨智能体、跨人。

English · · 日本語

官网 · 快速开始 · 手动启动 · 集成 · 基准测试 · 接口

PowerContext 是什么？

PowerContext 是面向 AI 智能体的开源上下文服务。 它把工作中需要长期留存的部分 —— 决策、约束、证据、进展 —— 放到任何单次对话之外，这样下一个会话、下一个智能体、下一个人都能从当前状态接着做，不必重读聊天记录。

你可以把它当作开箱即用的 Server 直接运行，也可以把同一套契约嵌入其他应用：

| 层 | 负责什么 | 什么时候用 |
| 核心协议 | Source、Artifact、Trigger 契约 | 嵌入 PowerContext，或新增组件 |
| 内置运行时 | Memory、Handoff、Experience、Skill 服务，调度、推理，以及支持的存储后端 | 运行标准的本地 Server |
| Server 与集成 | HTTP/MCP、Python Client、CLI、Dashboard、智能体插件 | 接入智能体或应用 |

工作很少由发起的人一路做完。你把任务交给智能体，智能体推进一段，之后你或别人接手。推理过程和当前状态往往留在那次对话里。PowerContext 把它们从对话里拿出来，存成可查看、带版本号的 artifact：

你和智能体交接工作，并带着已存储的上下文继续

一切都归属于一个 Scope —— 一份隔离的 Source 日志、Memory 生命周期、审核收件箱和 Handoff 历史。Scope ID 只用来选择数据，不证明用户身份，不授予工具访问权限，也不授权执行。

Scope
├── Source journal # evidence: prompts, documents, work contracts, task outcomes
├── Memory # atomic-memory/ARTIFACT_ID@REVISION — decisions, constraints, next steps ├── Review Inbox # pending Experience and Skill candidates awaiting a decision ├── Handoff history # handoff/ARTIFACT_ID@REVISION — work continuity across sessions └── Topic Memory # extracted in the background from eligible Sources Kubernetes 部署搭配外部 OceanBase 时，参见 Helm chart 与部署指南。

下方 Dashboard 截图使用合成的演示记录。

Memory——跨越会话存续的决策与约束

Memory 是一个带版本号的 Artifact 家族，存放可复用的决策、约束、事实、状态和后续步骤。条目状态为 active、forgotten、merged 或 retired。通过 POST /v1/atomic-memory/lifecycle 遗忘某条记录，会把它移出活跃召回，内容与历史仍然可查、可恢复，且不推进内容版本号。显式写入 Memory 完全不需要模型；从采集到的 Source 中抽取，则需要配置好生成流水线。

「别重构旧的 auth 模块——移动端还在用它。」
这么贵的上下文，不该指望有人每个会话都重复一遍。

Dashboard 展示某个 Scope 下的活跃决策与约束，以及它们引用的 Artifact 和 Source

Handoff——当前状态，而非整份对话记录

Handoff 以四步循环记录工作的连续性：

Work Contract → Prepared Handoff → Acknowledgement → Task Outcome

handoff_current_work 捕获一个已检查的边界，返回临时的 Prepared Handoff。只有用户想要里程碑时，提交它才会创建持久 Revision。接收方解析 Handoff 并记录 Acknowledgement；Task Outcome 把最终状态与检查结果作为 Source 证据留存。Handoff Report 会投影每个选中 Scope 中最新的 Revision——只读，绝不改写 Memory。

Dashboard 展示已提交的 Handoff Revision，含记录的进度、下一步动作和关联的 source 证据

Experience——什么管用，复用前先评审

Experience 记录一个情境、一个动作、一个观察到的结果，以及一条可复用的经验。它作为待定 Candidate 进入 scope 本地的 Review Inbox。评审写入使用 expected_version，因此别的写入者改了提案后，决策不会悄悄生效。批准会写入不可变 Revision；拒绝会记录原因。两者都是终态，只有已批准的当前 head 参与召回——待定、已拒绝和历史 Revision 一律排除。

Skill——经过评审的流程，按需导出

托管的 Skill 包含名称、发现描述、指令、校验检查和血缘。批准并不会安装或执行它：必须显式导出某个确切的已批准 Revision，Agent 宿主才能发现宿主本地的投影。

运维指标 暴露依赖观测、处理新鲜度和尝试延迟，其中包含一个受保护的仅指标端点，供独立后台部署使用。

为什么选 PowerContext？

- 上下文活在对话之外。 Memory、Handoff、Experience 和 Skill 都是服务端产物，不是某个智能体主目录里的文件。从 Codex 换到 Claude Code，或者把工作交给队友，工作都会跟着你走。
- 一切都可修订、可追溯。 每个 Artifact 都按 FAMILY/ARTIFACT_ID@REVISION 寻址。Artifact ID 保持稳定，获批的替换会生成后续 Revision；即使家族头已前进，读取精确引用仍返回那份历史快照。
- 生成、评审、执行是分开的步骤。 模型提出内容，评审批准 Revision，导出创建宿主机本地副本。这些步骤都不会授予智能体执行指令的权限。各接口当前暴露什么，见 Interfaces。
- 召回有边界，不是全量倾倒。 PreparedContext 从活跃 Memory 和已批准的 Experience 中选取配置好的段落，可选带上 Profile 快照和 Topic Memory，然后套用共享的字节预算，返回 ready 内容或 empty。召回的内容是历史，不是指令权威：接收方智能体仍要遵循当前指令，并检查实时工作区状态。
- 复用之前先评审。 Experience 和 Skill 都要经过评审决定，无论结果如何都是终局；批准会写入不可变的 Revision。启用访问控制后，批准需要 scope.review。有权限的智能体可以批准自己的 Candidate；当必须由人决定时，用不同身份和权限把提交与评审分开。
- 一个 Server，同一契约的多种视图。 HTTP 是完整的远程应用契约。Python Client 提供类型化访问，MCP 是精选的、面向智能体的投影，Core 协议让应用自行组装 Source、Artifact 和 Trigger 实现。

对比

对比假设典型的单智能体或宿主机本地部署；具体行为取决于各系统如何部署。

| | 重读聊天历史 | 对转录做 RAG | 宿主机本地记忆文件 | PowerContext |
| 跨新会话保留 | 手动 | 是 | 是 | 是 |
| 跨智能体切换保留 | 否 | 否 | 否 | 是 |
| 把工作交给他人 | 手动 | 手动 | 手动 | Handoff，一等公民 |
| 可复用流程 | 否 | 否 | 仅散文 | Experience / Skill |
| 保留早期修订 | 否 | 取决于索引 | 仅通过 git | 不可变 Revision |
| 复用前评审 | 不适用 | 否 | 否 | Review Inbox |
| 单轮有界召回 | 否 | 部分 | 否 | PreparedContext 字节预算 |
| 可在智能体外检查 | 否 | 否 | 是 | 是 |

有效性验证

PowerContext 在 LoCoMo 和 SWE-bench Pro 上的精简对比结果

- 长对话记忆（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 候选过滤的 PowerContext。每个模型同时用于 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 分 |

完整方法、结果与局限：benchmarks。有两处需要说明，我们不想藏着掖着：上面六个 LoCoMo Plus 分数由项目所有者提供，其运行产物未公开，无法验证 —— 公开的说明只能复现测试框架，复现不了这些分数。Windows 支持为 experimental。

快速开始

如果你想手动配置并启动 PowerContext，见手动启动指南。

PowerContext 把持久的项目上下文放在任何单个聊天之外。首次运行走这条路径：

Agent input → Source evidence → Memory / Topic Memory → PreparedContext → next session or Agent

PowerContext 1.4.1 带交互式安装向导。你需要 Python 3.11+、Git 和 uv；需要时 uv 可以自行准备 Python。要连接智能体，还需安装它的命令行。在向导里，选 Basic memory 可显式保存和召回，不需要模型 API；Full memory 需要单独的 Generation 和 Embedding API 凭据。想在没有模型 API 的情况下跑本地 Server，见安装与运行。支持 macOS 和 Linux；Windows 支持为 experimental。

按你的目标选路径：

| 目标 | 选择 | 需要什么 |
| 试用显式保存和召回 | Basic memory | 命令行和 Server；不需要模型 API |
| 自动处理 Source，并使用 Topic Memory 或语义检索 | Full memory | 单独的 Generation 和 Embedding API 凭据；调度和 Scope 策略仍然生效 |
| 用 Python 学习核心工作流 | 前七个 Jupyter 教程 | 检出仓库和 uv；不需要模型或 API key |

1. 安装并运行向导

uv tool install --force "powercontext[cli,server]==1.4.1"bash
mkdir -p powercontext-config && cd powercontext-config
powercontext config init --language en --output .env
powercontext config validate --env-file .env
powercontext server run --env-file .env # keep this terminal open

向导会询问存储、本地或远程使用、记忆能力、Dashboard/访问方式，以及 Agent 连接。SQLite 是最简单的首选存储；只有确实需要 embedded seekdb，并且能批准它安装依赖时，才选它。

向导会写出一个 .env 环境文件和 .env.next-steps.md。这些文件可能包含凭据，不要提交。保持 Server 运行；在另一个终端里回到 powercontext-config，重新加载生成的环境文件，然后检查连接： bash
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 安装是： bash powercontext setup codex --ref powercontext-v1.4.1 powercontext doctor codex

在新的 Codex 会话里发送第一条消息之前，打开 /hooks，出现提示时信任 PowerContext 钩子。没有启用的 UserPromptSubmit 钩子，自动提示词捕获和召回就不会运行，即使 MCP 已连接。参见首次会话检查与恢复。
完成下面的首次检查后，用能力与触发指南试用全部七个 Artifact 家族、Source 和 Tag。基础记忆不需要单独的 Server 模型 API；Agent 仍然使用自己的模型。

2. 验证首个端到端结果

这一步检查让 PowerContext 有用的路径：Source 捕获 → 后台处理 → 跨会话召回。在绑定同一 Scope 的新 Agent 会话里，发送一条具体决策，例如： text We are designing the Aurora acceptance project. Use uv for Python dependencies and .env for configuration. The first deployment runs on one Linux server, with a Mac connecting through an SSH tunnel. Restate these constraints without changing any code.

如果启用了 Dashboard，打开向导打印的 URL；捕获前 Dashboard 为空是正常的。然后：

1. 确认提示词作为 Source 出现。
2. 经过配置的检查间隔和模型处理后，确认出现相关的 Topic Memory。
3. 发送一条相关更新，确认新的 Source 已经到达，并且主题内容或修订历史中体现了这条更新。
4. 用相同的 Scope 启动新的 Agent 会话，要求给出 Aurora 决策并附上引用。

doctor codex 只检查安装和连通性。Source 捕获本身不会创建 Memory 或 Topic Memory，处理过程可能要等配置好的调度和模型工作完成。在 Basic memory 模式下，明确要求 Agent 保存一条决策，然后在新会话中搜索它；这并不能测试自动提取。

3. 先探索 Python —— 无需 API key

教程从仓库检出运行，依赖来自 uv 依赖组，因此不属于 powercontext 包。在仓库根目录执行： bash
uv sync --locked --group notebooks
uv run --locked --group notebooks jupyter lab --notebook-dir=examples/jupyter

先看 01 · Memory across sessions，然后按顺序完成 22 篇中文 Jupyter 教程和一套完整的团队工作流，一步步运行 Memory、上下文准备、Handoff、Experience、Skill 和真实的 Agent 步骤。前七篇教程不需要模型或 API key。

常见问题

- doctor codex 验证 Codex 安装和连通性。要验证自动记忆，请检查真实提示词是否变成 Source、是否产生 Topic、在相关提示词之后是否演进，以及能否在新会话中用相同 Scope 召回。
- 如果 Python 依赖下载慢或失败，为 uv 配置包索引后重试。
- 选择 Full memory capabilities 测试自动 Memory 和 Topic Memory；这需要单独的 Generation 和 Embedding API 凭据。Agent 订阅不提供这些 Server 凭据。选择 Basic memory 可以显式保存和检索记忆，无需额外的模型 API。
- 如果需要安装 seekdb，向导会询问一次，然后在后台安装依赖。
- 可选的召回充分性门控会记录 scope 本地的每日搜索投入和预算省略，供后续策略评估。记录和失败行为见配置参考。
- 如果 Server 在另一台机器上，请使用 HTTPS，或遵循远程连接指南。安装程序会从命令行参数或环境变量识别远程 HTTP URL，并请求明确同意；自动化安装使用 --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

应用可以通过异步 Python 客户端、HTTP API、MCP 或进程内 Core SDK 使用 PowerContext。选哪个入口，见接口参考。

构建 PowerContext bash
make install
make check
make test

完整开发流程见 CONTRIBUTING.md。
编码与记忆评测、性能基准、技能回归都放在 evaluation/ 下。

了解更多

- 快速上手
- 接入智能体
- 管理上下文
- 部署与运维
- 用 API 开发

PowerContext 是 PowerMem 的后继项目。

贡献者

感谢每一位为 PowerContext 做出贡献的人。❤️

查看全部贡献者 ·开始贡献

许可

PowerContext 采用 Apache License 2.0 许可。