安装并运行 Server

先把最小 Server 跑起来。第一次不要接模型。

先把最小 Server 跑起来。它没有生成或嵌入模型，但已经能保存你写下的 Memory，做全文搜索，并通过 HTTP、Python Client 和 MCP 读写同一套数据。

第一次不要接模型。这样卡住时，只需要查安装、数据目录、Scope 和连接。这条闭环通了，再加推理。否则模型提供方出问题，很容易被看成数据库或接入坏了。

安装参数、接口说明和部署配置，以 官方文档 的最新发布版本为准。这页只帮你把本地 Server 跑起来，并确认它现在能做什么。

当前写清的安装路径是 macOS 或 Linux，Python 3.11 及以上。本教程不提供未经验证的 Windows 变通方案。

​

前置条件

当前写清的安装环境是：

• macOS 或 Linux；
• Python 3.11 及以上；
• Git；
• uv。

PowerContext 支持 Python <4.0。

​

安装 CLI 和 Server

从当前 master 安装：

uv tool install --force \
  "powercontext[cli,server] @ git+https://github.com/oceanbase/powercontext.git@master"

uv tool 使用隔离环境，不会在当前目录留下仓库检出。--force 也用于更新：如果同一个 Git 依赖声明已安装，它会重新获取所选版本引用，而不是直接报告已安装。

本地学习可以跟着你正在读的那一页里的版本引用走。本页和通用 / 编程 Agent 安装配置用 @master，方便跟上当前教程。

可复现部署不要跟 master。先选定一个经过验证的提交，再让 CLI、Server 和宿主插件使用同一个版本引用。需要固定版本时写成完整提交哈希，不要在同一组命令里混用短哈希和长哈希。

uv tool 里的 powercontext[client] 不能被另一个 Python 项目直接导入。需要写客户端代码时，稍后还要把客户端附加依赖安装到那个项目自己的环境中。

​

启动本地 Server

powercontext server run

默认配置如下：

项目	默认行为
地址	http://127.0.0.1:8000
Dashboard	/
Streamable HTTP MCP	/mcp；用法见用 MCP 连接 Server
数据库	用户数据目录中的持久 SQLite
Bearer 认证	关闭，仅适合默认本机回环地址使用
生成 / 嵌入	未配置
搜索	auto、fts

macOS 上，数据库通常位于：

~/Library/Application Support/powercontext/powercontext.db

Linux 通常位于：

~/.local/share/powercontext/powercontext.db

设置 POWERCONTEXT_HOME 后，默认数据库会放到该目录。换了数据目录或数据库 URL，你看到的是另一套库。这很像 Scope 丢了。

Ctrl-C 会正常关闭 Server。再次运行命令会打开同一个数据库。

​

检查运行状态

另开一个终端：

powercontext doctor
powercontext ready
powercontext capabilities

三条命令问的不是同一件事。

​

doctor

检查当前软件包、Server 存活状态和就绪状态。全部为 ok 时退出码才是 0。

如果存活状态失败，就绪状态会标为已跳过。degraded 也会让诊断返回非零，因为至少一个已配置推理检查没通过；这不等于数据库必然不可用。

​

ready

区分：

• ready：所有已配置检查通过；
• degraded：可选推理检查失败，HTTP 仍为 200；
• not_ready：运行时或数据库不可用，就绪状态端点返回 HTTP 503。当前 CLI 会把这个 503 打印成 Server 错误，而不是完整展开 not_ready 响应；用 doctor 或直接检查 /health/ready 诊断依赖项。

​

capabilities

最小 Server 应显示类似：

Source types: content
Artifact families: memory, experience, skill, handoff
Memory extraction: disabled
Experience generation: disabled
Managed Skill generation: disabled
External Skill Registry: disabled
Handoff generation: disabled
Search modes: auto, fts
Context versions: powercontext.prepared-context.v1

能力列表中出现某类 Artifact，不代表相应的模型生成功能已经开启。请以对应的能力布尔值为准。

打开 Dashboard：

http://127.0.0.1:8000/

没配 Dashboard 的 Scope 时，页面就是空的。Dashboard 初始化失败只会记一条警告；HTTP API 和 MCP 还能继续用。要核对同一 Scope 的数字，按用 Dashboard 核对 Scope 统计 配上相同的 scope_id。

​

先验证不接模型时能做什么

最小 Server 可以完成：

• 采集 Source；
• 显式 Memory 记住、搜索、修订和停用；
• FTS；
• 类型化 Experience / Skill 提案与 Candidate Review；
• 已准备 Handoff 定稿、提交和继续；
• PreparedContext 构造，只要当前 Scope 有可召回内容。

它不能完成：

• Source 到 Memory 的模型抽取；
• Experience / Skill / Handoff 的模型生成；
• 向量 / 混合搜索；
• 模型驱动的重排序。

所以第一条闭环从你已经确认的 Memory 开始：写下来，用 search_memory 找到它，再通过 prepare_context 得到带 Citation 的 PreparedContext。先确认数据还在、Scope 对、Citation 在，再把模型提供方加进来。从 Source 抽取 Memory，以及用模型生成 Handoff，留到后面的页。

​

为 Python 项目安装客户端

在要运行示例的 Python 项目中：

uv add \
  "powercontext[client] @ git+https://github.com/oceanbase/powercontext.git@master"

确认该项目使用 Python 3.11 或以上：

uv run python --version

下一页的示例通过：

from powercontext.client import PowerContextClient
from powercontext.http import RememberMemoryRequest

导入公共 API。不要从 powercontext.http._generated 导入内部生成模块。

​

.env 不会自动加载

PowerContext CLI 不会搜索当前目录的 .env。需要显式传入：

powercontext server run --env-file .env

完整能力可以从配置生成器开始：

powercontext config init --output .env
powercontext config show --env-file .env
powercontext config validate --env-file .env
powercontext server run --env-file .env

生成和调度器要分开配。配了生成模型，抽取能力会打开，但定时调度器不会自动开。你仍可以手动调用 flush_memory。

嵌入必须把模型、配置档 ID 和维度成组配齐。缺任何一项，配置校验应失败，而不是启动一套说不清的半向量模式。

​

认证与远程访问

默认配置只监听本机回环地址，所以关闭认证是可接受的本地开发设置。

绑定非本机回环地址时，Server 默认要求认证；否则必须显式启用不安全选项。Python Client 也拒绝访问非本机回环地址的明文 HTTP。生产和远程部署应使用 TLS 和 Bearer 令牌，不要把令牌放进 URL。

开启认证后，客户端从环境读取裸令牌：

export POWERCONTEXT_CLIENT_API_TOKEN="replace-with-token"

它会构造：

Authorization: Bearer replace-with-token

​

启动时常见卡点

​

doctor 显示 Server 不可达

确认 powercontext server run 还在跑，并检查 8000 端口有没有被占用。若用了自定义地址，把 doctor 自己的选项放在子命令后：

powercontext doctor \
  --server-url http://127.0.0.1:9000

根命令的 --server-url 用于客户端内容命令，不会替代 doctor 的独立地址参数。

​

创建了 .env，能力仍没变化

启动命令有没有带 --env-file .env？CLI 不会自己去读它。

​

capabilities 只有 auto, fts

Server 在只做全文搜索的模式下是正常的。向量或混合搜索的前提还没配齐。

​

ready 是降级

看具体是哪一项依赖没过。不依赖那项推理能力的数据库操作可能还能用；需要该模型提供方的操作仍会失败。

​

重启后看不到旧数据

检查 POWERCONTEXT_HOME、数据库类型和数据库 URL 有没有变，再检查 scope_id。这三处都会换掉你看到的数据。对不上时，先看排错。

​

怎么知道跑通了

继续前确认这几件事：

• powercontext doctor 在最小配置下通过。
• powercontext capabilities 显示 auto, fts。
• Dashboard 能打开，或你已经明确关掉它。
• 示例 Python 项目能导入 PowerContextClient。
• 本教程用的稳定 Scope 是 project:powercontext-101。
• 下一条要做的事是：写出 Memory，用 search_memory 找到它，再通过 prepare_context 拿到带 Citation 的 PreparedContext。

​

下一步

常用 API 串讲

用 Python Client 写出一条 Memory，搜到它，再拿到带 Citation 的 PreparedContext。

跑第一条闭环

卡住时先对排错

搜不到、页面是空的，或诊断过了还是不行，先打开排错。

打开排错