diff --git a/README.md b/README.md
index 5775688237..33cb5976d8 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
# PowerContext
-Context for work that humans and agents hand off and continue.
+**Context that stays with the work — across sessions, agents, and people.**
[](https://pypi.org/project/powercontext/)
[](LICENSE)
@@ -8,57 +8,149 @@ Context for work that humans and agents hand off and continue.
*[English](README.md) · [中文](README_CN.md) · [日本語](README_JP.md)*
-Work rarely ends with whoever starts it. You hand a task to an agent, the agent gets part of the way, and later you or someone else takes over. The reasoning and current state often stay behind in that conversation.
+[Website](https://powercontext.oceanbase.io/) · [Quickstart](https://powercontext.oceanbase.io/en/docs/get-started/quickstart/) · [Integrations](https://powercontext.oceanbase.io/en/docs/integrations/) · [Benchmarks](https://powercontext.oceanbase.io/en/benchmarks/) · [Interfaces](https://powercontext.oceanbase.io/en/docs/develop/interfaces/)
-PowerContext keeps context with the work across conversations. When you return, you can see what happened and continue from the current state. A new agent can do the same.
+## What is PowerContext?
+
+**PowerContext is an open-source context service for AI agents.** It keeps the durable part of your work — decisions,
+constraints, evidence, progress — outside any single conversation, so the next session, the next agent, or the next
+person can pick up from the current state instead of rereading the transcript.
+
+Work rarely ends with whoever starts it. You hand a task to an agent, the agent gets part of the way, and later you or
+someone else takes over. The reasoning and current state often stay behind in that conversation. PowerContext moves them
+out of the conversation and into revisioned artifacts you can inspect:
-[Website](https://powercontext.oceanbase.io/) · [Installation walkthrough](https://powercontext.oceanbase.io/en/docs/get-started/quickstart/)
+Everything belongs to a **Scope** — one isolated Source journal, Memory lifecycle, review inbox, and Handoff history.
+A Scope ID selects data; it does not prove user identity, grant tool access, or authorize execution.
-PowerContext 1.3.0 includes the guided setup. The commands below install this version and connect
-the matching Agent integration.
+```text
+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
+```
-## Pick up where the work left off
+*The Dashboard screenshots below use synthetic demonstration records.*
-You see the context the work needs now: confirmed decisions, constraints, progress, evidence, and next steps. You can continue from there or hand the work to another person or agent without rereading the full history.
+### Memory — decisions and constraints that outlive a session
-You decide what will matter later and what needs to move with the task. PowerContext stores durable information as Memory and organizes the current objective and state into a Handoff. You can record reusable approaches as Experience or Skill. PowerContext keeps every item within the scope of the work and preserves its sources and earlier revisions.
+Memory is a revisioned Artifact family for reusable decisions, constraints, facts, state, and next steps. An entry is
+`active`, `forgotten`, `merged`, or `retired`. Forgetting one through `POST /v1/atomic-memory/lifecycle` takes it out of
+active recall while its content and history stay available and restorable, without advancing the content revision.
+Explicit Memory writes need no model at all; extraction from captured Sources needs a configured generation pipeline.
-The optional recall-sufficiency gate records scope-local daily search effort and budget omissions for later policy
-evaluation. See the [configuration reference](docs/en/docs/operate/configuration.md) for its recording and failure behavior.
+> "Don't refactor the old auth module — mobile is still using it."
+> Context this expensive shouldn't depend on someone repeating it in every session.
-## Install, configure, and connect your Agent
+
-You need Git, [uv](https://docs.astral.sh/uv/getting-started/installation/), and your Agent's CLI.
-Python 3.11+ is required; uv can provision it. macOS and Linux are supported; Windows support is `experimental`.
+### Handoff — the current state, not the whole transcript
-Install 1.3.0 and open the interactive configuration wizard in a dedicated directory:
+Handoff records work continuity as a four-step loop:
-```bash
-uv tool install --force "powercontext[cli,server]==1.3.0"
-mkdir -p powercontext-config
-cd powercontext-config
-powercontext config init --language en --output .env
+```text
+Work Contract → Prepared Handoff → Acknowledgement → Task Outcome
```
-If Python dependency downloads are slow or fail, follow the [mirror retry instructions](https://powercontext.oceanbase.io/en/docs/get-started/install-and-run/#retry-dependency-downloads-with-a-mirror).
+`handoff_current_work` captures an inspected boundary and returns a temporary Prepared Handoff. Committing it creates a
+durable Revision only when the user wants a milestone. The receiver resolves the Handoff and records an Acknowledgement;
+a Task Outcome preserves the final status and checks as Source evidence. The
+[Handoff Report](https://powercontext.oceanbase.io/en/docs/workflows/use-handoff-report/) projects the latest Revision in
+each selected Scope — read-only, and it never rewrites Memory.
+
+
+
+### Experience — what worked, reviewed before it is reused
+
+An Experience records a situation, an action, an observed outcome, and a reusable lesson. It enters a scope-local Review
+Inbox as a pending Candidate. Review writes use `expected_version`, so a decision cannot silently apply after another
+writer changes the proposal. Approval writes an immutable Revision; rejection records a reason. Both are terminal, and
+only the approved current head takes part in recall — pending, rejected, and historical Revisions are excluded.
+
+### Skill — a reviewed procedure, exported on purpose
+
+A managed Skill holds a name, a discovery description, instructions, validation checks, and lineage. Approval does not
+install or execute it: an exact approved Revision must be exported explicitly before an Agent host can discover the
+host-local projection.
+
+## Why PowerContext?
+
+- **Context lives outside the conversation.** Memory, Handoff, Experience, and Skill are server-side artifacts, not
+ files inside one agent's home directory. Switch from Codex to Claude Code — or hand the work to a teammate — and the
+ work travels with you.
+- **Everything is revisioned and traceable.** Each Artifact is addressed as `FAMILY/ARTIFACT_ID@REVISION`. The Artifact
+ ID stays stable while approved replacements create later Revisions, and reading an exact reference returns that
+ historical snapshot even after the family head advances.
+- **Generation, review, and execution are separate steps.** A model proposes content, review approves a Revision, and
+ export creates a host-local copy. None of those steps grants an Agent permission to execute instructions. See
+ [Interfaces](https://powercontext.oceanbase.io/en/docs/develop/interfaces/) for what each surface exposes today.
+- **Recall is bounded, not dumped.** `PreparedContext` selects active Memory and approved Experience heads for one Agent
+ turn, applies a shared byte budget, and returns `ready` content or `empty`. Recalled content is history, not an
+ instruction authority: the receiving Agent still follows current instructions and checks live workspace state.
+- **Review before reuse.** Experience and Skill pass through a review decision that is terminal either way. The model
+ proposes rather than silently promoting its own output.
+- **One Server, several views of the same contract.** HTTP is the complete remote application contract. The Python Client
+ gives typed access, MCP is a curated Agent-facing projection, and Core protocols let an application assemble its own
+ Source, Artifact, and Trigger implementations.
+
+### How it compares
+
+| | Re-reading chat history | RAG over transcripts | Host-local memory files | PowerContext |
+|---|---|---|---|---|
+| Survives a new session | manual | yes | yes | yes |
+| Survives switching agents | no | no | no | yes |
+| Handing work to a person | manual | manual | manual | Handoff, first-class |
+| Reusable procedure | no | no | prose only | Experience / Skill |
+| Earlier revisions kept | no | depends on the index | only via git | immutable Revisions |
+| Review before reuse | n/a | no | no | Review Inbox |
+| Bounded recall for one turn | no | partial | no | `PreparedContext` byte budget |
+| Inspectable outside the Agent | no | no | yes | yes |
+
+## Proof it works
+
+
+
+- **Long-conversation memory (LoCoMo): 90.78% accuracy**, against 87.79% for PowerMem and 52.9% for full-context replay
+ — **+37.88 points** over full context.
+- **Coding tasks (SWE-bench Pro): 86.73% task resolution with PowerContext on, 82.35% with it off** — **+4.38 points**
+ and 32 more tasks resolved in a 731-task paired run.
+- **Retrieval quality (LoCoMo Plus)**, native PowerContext against PowerContext with Jev candidate filtering after
+ retrieval. Each model is used for both Memory extraction and answering; embeddings use `qwen3.7-text-embedding`
+ (1024 dimensions):
-The wizard asks about storage, local or remote access, memory capabilities, Dashboard, model APIs, and Agent
-connections. Choose **Full memory capabilities** to test automatic Memory and Topic Memory; this requires separate
-Generation and Embedding API credentials. An Agent subscription does not provide those Server credentials.
-Choose **Basic memory** to save and retrieve memories explicitly without additional model APIs.
+ | Model | PowerContext | PowerContext + Jev | Difference |
+ |---|---|---|---|
+ | GPT-4o-mini | 40.855% | 49.78% | +8.925 points |
+ | Qwen3.7-plus | 60.37% | 68.947% | +8.577 points |
+ | GPT-4o | 65.082% | 69.28% | +4.198 points |
-The wizard writes one `.env` environment file and `.env.next-steps.md`.
-If seekdb needs installing, it asks once and installs the dependency in the background. Follow the printed
-connection details and start Server in this terminal:
+Full methods, results, and limitations: [benchmarks](https://powercontext.oceanbase.io/en/benchmarks/). Two caveats we
+would rather state than bury: the six LoCoMo Plus scores above were supplied by the project owner, and their run
+artifacts are not publicly available for verification — the published instructions reproduce the harness, not those
+scores. Windows support is `experimental`.
+
+## Quick start
+
+PowerContext 1.3.0 includes an interactive setup wizard. You need Git,
+[uv](https://docs.astral.sh/uv/getting-started/installation/), and your Agent's CLI. Python 3.11+ is required; uv can
+provision it. macOS and Linux are supported; Windows support is `experimental`.
+
+
+Run the wizard in a dedicated directory
```bash
-powercontext server run --env-file .env
+uv tool install --force "powercontext[cli,server]==1.3.0"
+mkdir -p powercontext-config && cd powercontext-config
+powercontext config init --language en --output .env
+powercontext server run --env-file .env # keep this terminal open
```
-Keep Server running. In another terminal, return to `powercontext-config`, load only the client settings,
-and check the connection:
+The wizard writes one `.env` environment file and `.env.next-steps.md`. Keep Server running; in another terminal, return
+to `powercontext-config`, load only the client settings, and check the connection:
```bash
set -a
@@ -68,26 +160,61 @@ powercontext ready
powercontext capabilities
```
-Continue with `.env.next-steps.md` to create and bind the selected Scopes, install the matching plugins, and launch
-a new Agent session. The [complete walkthrough](https://powercontext.oceanbase.io/en/docs/get-started/quickstart/)
-covers Codex and Claude Code, Dashboard login, SSH forwarding, HTTPS prerequisites, and observable acceptance checks.
-For example, the matching Codex installation is:
+Continue with `.env.next-steps.md` to create and bind the selected Scopes, install the matching plugins, and launch a new
+Agent session. The [complete walkthrough](https://powercontext.oceanbase.io/en/docs/get-started/quickstart/) covers Codex
+and Claude Code, Dashboard login, SSH forwarding, HTTPS prerequisites, and observable acceptance checks. For example, the
+matching Codex installation is:
```bash
powercontext setup codex --ref powercontext-v1.3.0
powercontext doctor codex
```
-`doctor` verifies integration setup. To verify automatic memory, check that a real prompt becomes a Source,
-produces a Topic, evolves after a related prompt, and can be recalled in a new session using the same Scope.
+
+
+
+Explore in Python first — no API key
-For a Server on another machine, use HTTPS or follow the
-[remote connection guide](docs/en/docs/operate/connect-remote-server.md). Setup recognizes remote HTTP URLs from
-flags or environment variables and asks for explicit consent; automated setup uses `--allow-insecure-http`.
+The tutorials run from a repository checkout and take their dependencies from a `uv` dependency group, so they are not
+part of the `powercontext` package. From the repository root:
-Codex is `official`; other hosts and Python Agent frameworks are `community`; Bub is `evaluation` only.
-These tags describe PowerContext integration maintenance and use. See the
-[capability matrix](https://powercontext.oceanbase.io/en/docs/integrations/capabilities/) for supported features and availability.
+```bash
+uv sync --locked --group notebooks
+uv run --locked --group notebooks jupyter lab --notebook-dir=examples/jupyter
+```
+
+Then work through the [22 Chinese Jupyter tutorials and a complete team workflow](examples/jupyter/README.md) to run
+Memory, context preparation, Handoff, Experience, Skill, and a real Agent step by step. The first seven tutorials need no
+model or API key.
+
+
+
+
+Before you ask "why isn't it working?"
+
+- `doctor` verifies integration setup. To verify automatic memory, check that a real prompt becomes a Source, produces a
+ Topic, evolves after a related prompt, and can be recalled in a new session using the same Scope.
+- If Python dependency downloads are slow or fail, configure a package index for
+ [uv](https://docs.astral.sh/uv/configuration/indexes/) and retry.
+- Choose **Full memory capabilities** to test automatic Memory and Topic Memory; this requires separate Generation and
+ Embedding API credentials. An Agent subscription does not provide those Server credentials. Choose **Basic memory** to
+ save and retrieve memories explicitly without additional model APIs.
+- If seekdb needs installing, the wizard asks once and installs the dependency in the background.
+- The optional recall-sufficiency gate records scope-local daily search effort and budget omissions for later policy
+ evaluation. See the [configuration reference](docs/en/docs/operate/configuration.md) for its recording and failure
+ behavior.
+- For a Server on another machine, use HTTPS or follow the
+ [remote connection guide](docs/en/docs/operate/connect-remote-server.md). Setup recognizes remote HTTP URLs from flags
+ or environment variables and asks for explicit consent; automated setup uses `--allow-insecure-http`.
+
+
+
+## Connect your Agent
+
+Codex is `official`; other maintained hosts and Python Agent frameworks are `community`; Bub is `evaluation` only.
+These tags describe PowerContext integration maintenance and use. The
+[capability matrix](https://powercontext.oceanbase.io/en/docs/integrations/capabilities/) records which hosts are
+qualified, along with their supported features and availability.
@@ -111,23 +238,8 @@ These tags describe PowerContext integration maintenance and use. See the
-Applications can use PowerContext through the async Python client, HTTP API, MCP, or the in-process Core SDK. See the [interface reference](https://powercontext.oceanbase.io/en/docs/develop/interfaces/) to choose an entry point.
-
-Explore the [22 Chinese Jupyter tutorials and a complete team workflow](examples/jupyter/README.md) to run Memory, context preparation, Handoff, Experience, Skill, and a real Agent step by step. The first seven tutorials need no model or API key.
-
-## What changes with PowerContext
-
-
-
-See the [methods, full results, and limitations](https://powercontext.oceanbase.io/en/benchmarks/) behind these comparisons.
-
-### LoCoMo Plus: comparison with Jev
-
-
-
-*LoCoMo Plus scores with and without Jev candidate filtering after retrieval. Each model is used for both Memory extraction and answering; embeddings use qwen3.7-text-embedding (1024 dimensions). Jev score differences are +8.925, +8.577, and +4.198 percentage points, respectively.*
-
-These six scores were supplied by the project owner; the run artifacts are not publicly available for verification. The reproducibility instructions describe the evaluation harness, not verification of these scores.
+Applications can use PowerContext through the async Python client, HTTP API, MCP, or the in-process Core SDK. See the
+[interface reference](https://powercontext.oceanbase.io/en/docs/develop/interfaces/) to choose an entry point.
## Build PowerContext
diff --git a/README_CN.md b/README_CN.md
index 29d1ab34da..8e4886ed83 100644
--- a/README_CN.md
+++ b/README_CN.md
@@ -1,6 +1,6 @@
# PowerContext
-为人和 Agent 交接并继续工作而生的上下文。
+**让上下文跟着工作走 —— 跨越会话、跨 Agent、跨人。**
[](https://pypi.org/project/powercontext/)
[](LICENSE)
@@ -8,53 +8,116 @@
*[English](README.md) · [中文](README_CN.md) · [日本語](README_JP.md)*
-工作很少会由开始它的人或 Agent 独自完成。你把任务交给 Agent，Agent 推进一部分，之后可能由你或其他人接手。推理过程和当前状态却常常留在那段对话里。
+[网站](https://powercontext.oceanbase.io/zh/) · [快速开始](https://powercontext.oceanbase.io/zh/docs/get-started/quickstart/) · [接入 Agent](https://powercontext.oceanbase.io/zh/docs/integrations/) · [评测](https://powercontext.oceanbase.io/zh/benchmarks/) · [接口](https://powercontext.oceanbase.io/zh/docs/develop/interfaces/)
-PowerContext 让上下文跟随工作，跨越不同的对话。你回来时，可以看到已经发生了什么，并从当前进展继续。新的 Agent 也能从同一处接手。
+## PowerContext 是什么？
+
+**PowerContext 是一个面向 AI Agent 的开源上下文服务。** 它把工作里值得长期保留的部分——已经确认的决定、约束、证据、进展——从某一次对话里搬出来，这样下一个会话、下一个 Agent、或者下一个接手的人，都能从当前进展继续，而不必重读全部记录。
+
+工作很少会由开始它的人或 Agent 独自完成。你把任务交给 Agent，Agent 推进一部分，之后可能由你或其他人接手。推理过程和当前状态却常常留在那段对话里。PowerContext 把它们从对话里移出来，变成可以查看、带版本号的 Artifact：
-[网站](https://powercontext.oceanbase.io/zh/) · [完整安装流程](https://powercontext.oceanbase.io/zh/docs/get-started/quickstart/)
+每一项内容都属于一个 **Scope**——一条独立的 Source 日志、一套 Memory 生命周期、一个评审收件箱和一份 Handoff 历史。Scope ID 只用于选取数据，它不证明用户身份、不授予工具访问权限，也不授权执行。
-PowerContext 1.3.0 包含交互式配置向导。下面的命令安装这一版本，并接入相同版本的 Agent 集成。
+```text
+Scope
+├── Source journal # 证据：输入、文档、工作契约、任务结果
+├── Memory # atomic-memory/ARTIFACT_ID@REVISION —— 决定、约束、下一步
+├── Review Inbox # 等待评审的 Experience 与 Skill 候选
+├── Handoff history # handoff/ARTIFACT_ID@REVISION —— 跨会话的工作接续
+└── Topic Memory # 由符合条件的 Source 后台提取
+```
-## 从当前进展继续
+*下面两张 Dashboard 截图使用的是合成演示记录。*
-你接手时，会先看到当前工作需要的上下文：已经确认的决定、约束、进展、证据和下一步。你可以从这里继续，也可以把工作交给其他人或 Agent，不需要重新翻阅全部记录。
+### Memory —— 活得比会话更久的决定与约束
-你决定哪些信息以后仍然有用，哪些内容需要随任务交给下一位接手者。PowerContext 把长期信息保存为 Memory，把当前目标和状态组织成 Handoff。你可以把能够复用的做法记录为 Experience 或 Skill。PowerContext 将每项内容限定在对应的工作范围内，并保留它的来源和历史版本。
+Memory 是一个带版本的 Artifact 家族，存放可以复用的决定、约束、事实、状态和下一步。条目状态为 `active`、
+`forgotten`、`merged` 或 `retired`。通过 `POST /v1/atomic-memory/lifecycle` 遗忘一条，会把它移出主动召回，但内容
+和历史仍然可用、可恢复，且不会推进内容 revision。显式写入 Memory 完全不需要模型；从已捕获的 Source 中提取，
+才需要配置生成流水线。
-可选的召回充分性门控会按 Scope 记录每日搜索工作量和字节预算遗漏，供后续策略评估使用。
-记录范围与失败行为见[配置说明](docs/zh/docs/operate/configuration.md)。
+> "别重构老的 auth 模块 —— 移动端还在用。"
+> 这么贵的上下文，不应该依赖有人每个会话都重讲一遍。
-## 安装、配置并接入 Agent
+
-准备 Git、[uv](https://docs.astral.sh/uv/getting-started/installation/) 和你使用的 Agent CLI。
-需要 Python 3.11+，uv 可以按需安装。支持 macOS 和 Linux；Windows 支持为 `experimental`。
+### Handoff —— 当前状态，不是整段对话记录
-安装 1.3.0，然后在独立目录里打开交互式配置向导：
+Handoff 用一个四步循环记录工作接续：
-```bash
-uv tool install --force "powercontext[cli,server]==1.3.0"
-mkdir -p powercontext-config
-cd powercontext-config
-powercontext config init --language zh --output .env
+```text
+工作契约 → Prepared Handoff → 确认回执 → 任务结果
```
-Python 依赖下载缓慢或失败时，可按[镜像重试步骤](https://powercontext.oceanbase.io/zh/docs/get-started/install-and-run/#使用镜像重试依赖下载)重新安装。
+`handoff_current_work` 抓取一个已经检查过的边界，返回一份临时的 Prepared Handoff。只有在你希望留下里程碑时，提交它才会生成持久的 Revision。接收方解析这份 Handoff 并记录确认回执；任务结果则作为 Source 证据保存最终状态与检查项。[Handoff Report](https://powercontext.oceanbase.io/zh/docs/workflows/use-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 执行指令的权限。各个入口目前各自暴露了什么，见[接口说明](https://powercontext.oceanbase.io/zh/docs/develop/interfaces/)。
+- **召回是有边界的，不是整包倾倒。** `PreparedContext` 会为这一轮 Agent 挑选活跃的 Memory 和已通过的 Experience 主版本，套用一个共享的字节预算，返回 `ready` 内容或 `empty`。召回的内容是历史，不是指令权威：接收方仍然要遵循当前指令，并检查工作区的实时状态。
+- **复用之前先评审。** Experience 和 Skill 都要经过一次评审决策，无论通过还是驳回都是终态。模型负责提议，而不是悄悄把自己生成的内容提上去。
+- **一个 Server，同一份契约的多个视图。** HTTP 是完整的远端应用契约。Python Client 提供带类型的访问，MCP 是面向 Agent 的精选投影，Core 协议则允许应用自行组装 Source、Artifact 和 Trigger 实现。
+
+### 横向对比
+
+| | 手动翻聊天记录 | 对聊天记录做 RAG | 宿主本地记忆文件（如 CLAUDE.md） | PowerContext |
+|---|---|---|---|---|
+| 跨会话留存 | 手动 | 是 | 是 | 是 |
+| 换 Agent 后仍可用 | 否 | 否 | 否 | 是 |
+| 把工作交给另一个人 | 手动 | 手动 | 手动 | Handoff，一等公民 |
+| 可复用的流程 | 无 | 无 | 仅自然语言描述 | Experience / Skill |
+| 保留历史版本 | 否 | 取决于索引 | 仅通过 git | 不可变 Revision |
+| 复用前经过评审 | 不适用 | 否 | 否 | 评审收件箱 |
+| 单轮召回有预算约束 | 否 | 部分 | 否 | `PreparedContext` 字节预算 |
+| 可以在 Agent 之外查看 | 否 | 否 | 是 | 是 |
+
+## 效果怎么样
+
+
+
+- **长对话记忆（LoCoMo）：准确率 90.78%**，PowerMem 为 87.79%，全量上下文重放为 52.9% —— 相对后者
+ **+37.88 个百分点**。
+- **编码任务（SWE-bench Pro）：开启 PowerContext 后任务解决率 86.73%，关闭时 82.35%** —— **+4.38 个百分点**，
+ 在 731 题的配对运行中多解出 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 个百分点 |
+
+评测方法、完整结果和适用边界：[官网评测页](https://powercontext.oceanbase.io/zh/benchmarks/)。有两点我们宁愿写明而不是藏起来：上面这六组 LoCoMo Plus 分数由项目方提供，运行产物尚未公开供复核——公开的是评测工具的复现步骤，不代表这些分数本身已被公开验证。Windows 支持为 `experimental`。
+
+## 快速开始
-向导会依次询问存储、使用场景、记忆能力、Dashboard、模型 API 和 Agent 连接。
-要体验自动 Memory 提取和 Topic Memory，请选择**完整记忆能力**并准备独立的 Generation、Embedding API 凭据；
-Agent 官方订阅不会自动给 PowerContext Server 提供这些凭据。选择**基础记忆**则可显式保存与召回，无需额外模型 API。
+PowerContext 1.3.0 包含交互式配置向导。需要准备 Git、[uv](https://docs.astral.sh/uv/getting-started/installation/) 和你使用的 Agent CLI。需要 Python 3.11+，uv 可以按需安装。支持 macOS 和 Linux；Windows 支持为 `experimental`。
-向导生成一个 `.env` 环境文件和 `.env.next-steps.md`。
-选择 seekdb 且缺少依赖时，会在确认后后台增量安装。按照最后打印的连接信息，在当前终端启动 Server：
+
+在独立目录里运行向导
```bash
-powercontext server run --env-file .env
+uv tool install --force "powercontext[cli,server]==1.3.0"
+mkdir -p powercontext-config && cd powercontext-config
+powercontext config init --language zh --output .env
+powercontext server run --env-file .env # 保持这个终端不关
```
-保持 Server 运行，在另一个终端回到 `powercontext-config` 目录，仅加载客户端配置并检查服务：
+向导生成一个 `.env` 环境文件和 `.env.next-steps.md`。保持 Server 运行，在另一个终端回到 `powercontext-config` 目录，仅加载客户端配置并检查服务：
```bash
set -a
@@ -64,21 +127,44 @@ powercontext ready
powercontext capabilities
```
-接着按 `.env.next-steps.md` 创建并绑定 Scope、安装相同版本的插件，再打开新 Agent 会话。
-[完整安装流程](https://powercontext.oceanbase.io/zh/docs/get-started/quickstart/)包含 Codex、Claude Code、Dashboard 登录、
-SSH 隧道、HTTPS 前提及逐项验收。例如，匹配本版本的 Codex 安装命令是：
+接着按 `.env.next-steps.md` 创建并绑定 Scope、安装相同版本的插件，再打开新 Agent 会话。[完整安装流程](https://powercontext.oceanbase.io/zh/docs/get-started/quickstart/)包含 Codex、Claude Code、Dashboard 登录、SSH 隧道、HTTPS 前提及逐项验收。例如，匹配本版本的 Codex 安装命令是：
```bash
powercontext setup codex --ref powercontext-v1.3.0
powercontext doctor codex
```
-`doctor` 通过只代表集成安装就绪。自动记忆验收需要确认：真实输入进入 Source、产生 Topic、相关输入推动主题演进，
-并能在使用同一 Scope 的新会话中召回。
+
+
+
+先用 Python 体验，不需要 API Key
+
+教程需要在仓库 checkout 内运行，依赖由 `uv` 的 dependency group 提供，不在 `powercontext` 包内。在仓库根目录执行：
+
+```bash
+uv sync --locked --group notebooks
+uv run --locked --group notebooks jupyter lab --notebook-dir=examples/jupyter
+```
+
+想用 Python 逐步体验？从 [22 篇中文 Jupyter 教程与完整团队工作流](examples/jupyter/README.md)开始，亲手运行 Memory、上下文、交接、Experience、Skill 和真实 Agent。前七篇不需要模型或 API Key。
+
+
+
+
+出问题之前，先看这几条
+
+- `doctor` 通过只代表集成安装就绪。自动记忆验收需要确认：真实输入进入 Source、产生 Topic、相关输入推动主题演进，并能在使用同一 Scope 的新会话中召回。
+- Python 依赖下载缓慢或失败时，可先为 [uv](https://docs.astral.sh/uv/configuration/indexes/) 配置包索引（镜像源）再重试。
+- 要体验自动 Memory 提取和 Topic Memory，请选择**完整记忆能力**并准备独立的 Generation、Embedding API 凭据；Agent 官方订阅不会自动给 PowerContext Server 提供这些凭据。选择**基础记忆**则可显式保存与召回，无需额外模型 API。
+- 选择 seekdb 且缺少依赖时，会在确认后后台增量安装。
+- 可选的召回充分性门控会按 Scope 记录每日搜索工作量和字节预算遗漏，供后续策略评估使用。记录范围与失败行为见[配置说明](docs/zh/docs/operate/configuration.md)。
+- Server 部署在另一台机器上时，请使用 HTTPS 或参考[远程连接说明](docs/zh/docs/operate/connect-remote-server.md)。Setup 会从参数或环境变量识别远端 HTTP 地址并要求显式确认；自动化场景使用 `--allow-insecure-http`。
-Codex 标为 `official`，其他宿主及 Python Agent 框架标为 `community`，Bub 标为 `evaluation`，仅用于评测。
-这些标签表示 PowerContext 集成的维护归属和用途，具体功能及可用状态见
-[能力矩阵](https://powercontext.oceanbase.io/zh/docs/integrations/capabilities/)。
+
+
+## 接入你的 Agent
+
+Codex 标为 `official`，其他受维护的宿主及 Python Agent 框架标为 `community`，Bub 标为 `evaluation`，仅用于评测。这些标签表示 PowerContext 集成的维护归属和用途；哪些宿主已通过资格验证、各自支持哪些功能，以[能力矩阵](https://powercontext.oceanbase.io/zh/docs/integrations/capabilities/)为准。