运行和使用 PowerContext Server

可直接运行的 Server 持有一个 BuiltinRuntime，并通过 HTTP 暴露它。同一个进程可以将一组经过筛选的 Memory operation 投影为 MCP tool。ServerSettings.mcp.enabled 控制该投影，因此 MCP 不需要独立入口或 extra。

安装和启动

同时安装 Server role 和 CLI，才能从命令行运行本实例：

uv add "powercontext[cli,server]"

启动 Server：

uv run powercontext server run

默认监听 127.0.0.1:8000，SQLite 数据保存在 powercontext.db。命令参数可以覆盖监听地址，但未认证的 Server 会拒绝 绑定到可路由地址：请启用 bearer 认证（推荐——在反向代理处终止 TLS），或在 TLS 已由上游终止 / 网络受控时显式 opt-in。

# 推荐：先为 Server 启用认证，再绑定可路由地址（生产环境在前面加 TLS）。
POWERCONTEXT_SERVER_ACCESS_MODE=enforced \
POWERCONTEXT_SERVER_AUTH_TOKEN="replace-with-a-strong-token" \
  uv run powercontext server run --host 0.0.0.0 --port 8080

# 或者，在 TLS 由上游终止 / 网络受控的前提下，显式 opt-in 到未认证绑定。
POWERCONTEXT_SERVER_ALLOW_UNAUTHENTICATED_NON_LOOPBACK=true \
  uv run powercontext server run --host 0.0.0.0 --port 8080

不带上述任一设置直接 --host 0.0.0.0 会以报错退出，而不会静默地暴露一个未认证的 Server。

进程会打开配置的 database，创建按 scope 隔离的 Builtin runtime，并在关闭时释放其持有的 database、inference 和 scheduler 资源。

Server 配置

ServerSettings 将 transport 和 Builtin 配置保持在同一层级：

环境变量使用 POWERCONTEXT_SERVER_ prefix，嵌套字段用下划线连接：

export POWERCONTEXT_SERVER_HTTP_PORT="8080"
export POWERCONTEXT_SERVER_DATABASE_URL="sqlite+aiosqlite:///data/powercontext.db"
export POWERCONTEXT_SERVER_RUNTIME_SOURCE_WINDOW_LIMIT="200"
export POWERCONTEXT_SERVER_MCP_ENABLED="false"

默认 database 是 SQLite。只需修改 discriminator 和 URL 即可选择 OceanBase：

export POWERCONTEXT_SERVER_DATABASE_KIND="oceanbase"
export POWERCONTEXT_SERVER_DATABASE_URL="mysql+aoceanbase://user:password@host:2881/powercontext?charset=utf8mb4"

两种 database 都通过同一组 Server API 提供全文检索。配置 embedding model 后，SQLite 使用 sqlite-vec，OceanBase 使用 HNSW 提供 vector 和 hybrid 检索。

inference 配置见配置 Pydantic AI 推理。

设置 POWERCONTEXT_SERVER_RUNTIME_SCHEDULE_SECONDS 可以按持久化 interval 处理待消费的 Source window。 定时 job 使用 POWERCONTEXT_HOME/scheduler.db 作为 SQLite sidecar。调度可以配合任一 application database 使用，但必须配置 generation pipeline。

HTTP 接口

契约源文件是 openapi/powercontext.yaml。powercontext.http._generated 下的 Pydantic model 和 operation descriptor 由该契约生成。

每个领域请求都包含 scope ID。该 ID 选择本地 runtime 使用的 Source journal、Memory head 和 Trigger cursor。 HTTP request model 是 transport value，与 Core domain model 保持独立。

Server error 使用 OpenAPI error schema，并在 response header 中包含由 inbound request span 派生的 Server-owned X-PowerContext-Request-ID。validation error、revision conflict、entry 不存在、inference unavailable 和内部 failure 会映射为稳定的 HTTP status code。

Server identity 与兼容性发现

GET /v1/server-info 受 server.observe 保护，返回稳定的 deployment server_id、已安装 package version、API contract version、response schema version 和首批 feature contract。它刻意不返回 health、已启用 runtime capability、limit、inventory、secret、文件系统 path 或已认证 principal；这些信息分别由 health、capabilities、 statistics 和 access endpoint 负责。

所有 discovery version 都使用 major >= 1 和 minor >= 0 的整数。major 增加表示受管契约可能被移除或发生不兼容变化；minor 增加只允许向后兼容的扩展。response 的 schema_version 管理字段与语义，api_contract_version 是 OpenAPI info.version 的 major/minor 投影。每个 feature contract version 只约束它列出的 OpenAPI operation ID：增加 operation 或兼容语义时增加 minor，移除、重命名或不兼容地改变已列 operation 时增加 major。兼容 client 必须忽略 schema minor version 新增的未知可选字段。

OpenAPI 根级 x-powercontext-feature-contracts 显式声明 feature version，各受管 operation 使用同名扩展声明归属。 make api-generate 从这些声明生成 discovery metadata，并拒绝超出上述范围的版本、未知或重复归属及没有 operation 的 feature。 版本号仍须显式修改，不会因归属变化而自动增加。

Server 使用 Runtime 持有的主关系数据库保存一条 identity singleton。启动时先幂等创建 identity table，再原子创建或读取 singleton，因此并发 initializer 会收敛到同一 ID，进程重启、package 升级、备份恢复以及共享同一数据库的 replica 也会保持该 ID。identity schema 初始化或读取失败时，Server 会在进入 readiness 之前直接启动失败，而不会发布 临时 identity。identity repository 只重试 SQLite busy/locked 错误，在事务回滚后重新执行完整的 schema 或 singleton 操作。重试窗口为五秒，每次等待 50 ms；每条 SQL 仍使用 driver 配置的 busy timeout。窗口耗尽或其他错误会直接 传播，离线轮换不重试。内存或临时 SQLite 没有持久存储，所以每个数据库生命周期都会获得新 ID。 使用同一共享内存 SQLite 数据库的 application 会共享数据和 identity；只要仍有 Runtime 连接，数据库就保持存活。 最后一个连接关闭后，再次打开会重新创建数据和 identity。 SQLite 存储分类使用 dialect 的实际连接参数和解码后的 URI，包括支持的 true 拼写（true、1、yes、on）以及 百分号编码的 :memory: path 以及内置的 vfs=memdb 内存文件系统。file:?uri=true 和 file:?cache=shared&uri=true 这类空路径 URI 创建的是连接独占的 临时数据库，而非持久文件。分类也遵循 SQLite 在解码后的 NUL 处终止文件名和查询参数名/值的行为：file:%00tail?uri=true 属于临时存储， 编码后的 :memory: 即使后接 %00 也仍是内存存储，SQLAlchemy URL 中的 mode=memory%2500tail 或 mode%2500tail=memory 也仍会选择原生 memory mode。只有精确的小写 file: 前缀才启用 SQLite URI 解释， 不会归一化大写 scheme、前导空格或文件名中的控制字符。SQLiteConfig.is_in_memory 区分内存存储；SQLiteConfig.is_persistent 同时排除内存与临时 存储。非持久存储的连接池保留一个连接；离线维护、cursor secret 持久化及子进程 worker 统一使用该持久性分类。

完整 Server 迁移已将 pc_server_identity 纳入冻结的 1.3.0 基线和共享版本链，并在 Runtime 组装前检查结构。迁移保留原有 singleton 值；deployment identity 与 pc_schema_revision 独立，升级不会轮换 server_id。clone 轮换仍是显式离线操作，identity 不另设 schema version 或 readiness marker。局部 Artifact bundle 不能证明完整 Server 就绪。

把备份恢复为原 deployment 时应保留原 ID。若用备份创建独立 clone，请停止所有使用 clone 数据库的 Server 进程，然后只在 clone 上轮换：

uv run powercontext server identity-reset --env-file /path/to/clone.env --maintenance-confirmed

该命令拒绝内存和临时数据库，并要求显式 maintenance confirmation。它无法检测仍在运行的 replica，因此停服是 operator 前置条件。逻辑 application-data import 不会复制 identity，除非显式包含 pc_server_identity 表。

Python Client

安装 Client role 以使用 SDK：

uv add "powercontext[client]"

PowerContextClient 是 async-native client，使用生成的 request 和 response model：

from powercontext.http import SearchMemoryRequest
from powercontext.client import PowerContextClient


async def search() -> None:
    async with PowerContextClient("http://127.0.0.1:8000") as client:
        server_info = await client.get_server_info()
        capabilities = await client.get_capabilities()
        result = await client.search_memory(
            SearchMemoryRequest(
                scope_id="project-alpha",
                query="composition root",
                limit=10,
                mode="auto",
            )
        )
        print(server_info.model_dump())
        print(capabilities.model_dump())
        print(result.model_dump())

client 使用 Pydantic 校验成功 response。transport failure、无效 response 和结构化 Server error 分别映射为 powercontext.client 中不同的 exception。

CLI

增加 CLI extra 后，已安装的 Client command 才会出现：

uv add "powercontext[cli,client]"

client command 提供进程和 capability 检查：

uv run powercontext live
uv run powercontext ready
uv run powercontext capabilities
uv run powercontext --json capabilities

可以通过 POWERCONTEXT_CLIENT_SERVER_URL 和 POWERCONTEXT_CLIENT_TIMEOUT 设置 client 默认值。

CLI 通过已安装 role 的 entry point 发现 command group。powercontext[cli] 默认提供 Builtin command；只有同时 安装 Client 或 Server role，相应 command 才会出现在帮助信息中。

MCP

MCP 默认启用并挂载到 /mcp。可以在不改变 HTTP API 的情况下关闭：

export POWERCONTEXT_SERVER_MCP_ENABLED="false"

修改 mount path：

export POWERCONTEXT_SERVER_MCP_PATH="/agent"

MCP 投影包含面向 agent 的 Memory operation，用于 search、list、read、remember、revise 和 retire entry；也包含 Candidate Review operation，用于 list、read、approve、reject 和 revise Candidate。health、capability、Source capture、 Experience、flush 和 change history endpoint 仍然只通过 HTTP 提供。

HTTP 和 MCP 共用同一个 Server application 和 Runtime binding。无论通过哪种 transport 发起请求，都会使用相同的 scope isolation、validation、并发校验和 persistence behavior。

程序化组合

自行托管 FastAPI 的应用可以构造同一个 service：

from powercontext.server.factory import create_server_app
from powercontext.server.settings import ServerSettings

app = create_server_app(settings=ServerSettings())

create_server_app() 持有内置 Runtime 的生命周期。测试或嵌入式应用可以注入 candidate_pipeline 或 embedding_model，无需替换整个生命周期。