配置¶

PowerContext 进程启动时从环境变量读取配置。

用户数据¶

POWERCONTEXT_HOME 可覆盖已安装 Server 使用的数据目录：

export POWERCONTEXT_HOME=/srv/powercontext

未覆盖时，默认目录为：

• Linux：$XDG_DATA_HOME/powercontext，未设置时为 ~/.local/share/powercontext；
• macOS：~/Library/Application Support/powercontext。

默认 SQLite 数据库是该目录下的 powercontext.db。启用定时处理时，调度状态保存在同一目录的 scheduler.db。

Server¶

Server 配置使用 POWERCONTEXT_SERVER_ 前缀。

静态 Bearer 鉴权默认关闭。启用后，API 和 MCP 请求必须携带 Authorization: Bearer <token>；liveness 和 readiness endpoint 仍然公开。明文 HTTP 应只用于 loopback 地址；通过网络暴露启用鉴权的 Server 前必须配置 TLS。

指定 SQLite 路径并启用定时提取的示例：

export POWERCONTEXT_SERVER_DATABASE_URL=sqlite+aiosqlite:////srv/powercontext/runtime.db
export POWERCONTEXT_SERVER_RUNTIME_SCHEDULE_SECONDS=30
export POWERCONTEXT_SERVER_INFERENCE_GENERATION_MODEL=provider:model-name
powercontext server run

OPENAI_API_KEY 等 provider 凭据由所配置的推理 provider 读取。不要把密钥放入命令行参数、文档或 Memory。请把 provider:model-name 替换为 Pydantic AI 支持的模型标识。定时提取需要同时配置 generation model 和 POWERCONTEXT_SERVER_RUNTIME_SCHEDULE_SECONDS；显式 Memory 写入不需要这两项配置。

默认的 coding 抽取 profile 保留跨任务工作上下文，例如偏好、决策、约束、昂贵事实和未完成进度。当产品 需要从对话证据中保留可独立回答的人物事实、关系、事件、精确日期、列表和历史状态时，可选择 conversation：

export POWERCONTEXT_SERVER_RUNTIME_MEMORY_EXTRACTION_PROFILE=conversation

profile 只影响后续 Source 处理，不会重新解释已有的 Memory revision。

当宽范围 Hybrid recall 比一次额外结构化 generation request 的延迟和 token 成本更重要时，可以启用面向回答的 Memory rerank：

export POWERCONTEXT_SERVER_INFERENCE_GENERATION_MODEL=provider:model-name
export POWERCONTEXT_SERVER_RUNTIME_MEMORY_RERANK_ENABLED=true
export POWERCONTEXT_SERVER_RUNTIME_MEMORY_RERANK_CANDIDATE_LIMIT=30

Rerank 默认关闭。启用后，Runtime 会召回并融合配置的候选池，再使用 temperature 为 0 的 generation model，选择不超过 search request 最终 limit 的结果。它不会修改已存储 Memory 或索引。Provider 与结构化输出失败仍作为 inference error 显式返回；如果搜索必须独立于模型可用性，请关闭 rerank。算法、并发与 API 边界见 RFC 0080。

同一个 generation model 也控制显式 Experience generation、managed Skill generation/evolution，以及 external Skill import/fork。未配置模型时，这些 operation 会在持久化 Candidate 前返回 capability error； Candidate Review、exact read 和 external Skill scan/list/resolve 仍可使用。

Experience 孵化使用独立的 APScheduler job 和持久化 Source cursor，可通过以下配置启用：

export POWERCONTEXT_SERVER_RUNTIME_EXPERIENCE_SCHEDULE_SECONDS=30
export POWERCONTEXT_SERVER_INFERENCE_GENERATION_MODEL=provider:model-name
powercontext server run

每次 activation 固定检查最多 32 条 Source，并且只把 metadata 包含 "kind": "task-outcome" 的 Content Source 暴露给模型。该 job 会在 Review Inbox 中创建 pending Experience Candidate；它不会自动批准、进入 PreparedContext、创建 managed Skill、将它导出给 Codex 或执行任何内容。Memory 和 Experience job 共用 POWERCONTEXT_HOME 下的 APScheduler sidecar，但拥有独立的 job identity 和业务 cursor；取消其中一个 interval 只会移除对应 job。

外部 Codex Skill¶

通过一个 JSON 值配置 host-local roots：

export POWERCONTEXT_SERVER_EXTERNAL_SKILLS='{
  "host_id": "workstation-1",
  "codex_roots": [
    {
      "root_id": "repository",
      "installation_scope": "project",
      "path": "/srv/project/.agents/skills"
    }
  ]
}'

每个 root ID 必须唯一；支持的 installation scope 是 user、project 和 plugin。PowerContext 只扫描这些 显式 root 的直接 Skill package 子目录，不会推断 home 目录、安装 package 或授予执行权限。host_id、locator 和 registration 都是本地环境状态，不是跨 host 或跨 Agent contract。

Server 始终创建 non-recording OpenTelemetry request context，从 inbound span 派生 X-PowerContext-Request-ID。如需为 CLI 管理的 Server 启用 recording 和 export，请安装 powercontext[cli,server,tracing-otlp]、启用 tracing， 并使用 OTEL_EXPORTER_OTLP_ENDPOINT、OTEL_EXPORTER_OTLP_HEADERS 和 OTEL_SERVICE_NAME 等标准 OpenTelemetry 环境变量进行配置。不使用 powercontext command 的 programmatic Server integration 可以省略 cli extra。

启用 tracing 后，PowerContext 自己构造的 generation 与 embedding 调用也会产生 span，且不记录 prompt、模型响应、 Memory 内容或向量。可运行的配置和唯一一处已记录的例外见 用 Phoenix 查看 trace。

使用 OceanBase 时，通过环境或 secret manager 提供 URL：

export POWERCONTEXT_SERVER_DATABASE_KIND=oceanbase
export POWERCONTEXT_SERVER_DATABASE_URL="$OCEANBASE_URL"

URL 必须使用 mysql+aoceanbase driver，包含明确的端口和数据库，并设置 charset=utf8mb4。对应 tenant 必须使用 MySQL 兼容模式。

Embedding¶

只有同时设置以下三个标识字段，才会启用 embedding 检索：

export POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_MODEL=provider:embedding-model
export POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_PROFILE_ID=embedding-model-v1
export POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_DIMENSION=1024

请把示例值替换为所选 provider model、稳定的 profile ID，以及该模型的 dimension。

可选设置包括 POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_NORMALIZATION 和 POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_TIMEOUT_SECONDS。

Embedding normalization 默认为 unit。

SQLite Vec1¶

SQLite vector 和 hybrid search 还需要 0.7 或更高版本的 SQLite Vec1 loadable extension。PowerContext 不负责下载、构建或更新 这个 native library。请先获取适用于 Server 操作系统和架构的构建产物，再同时配置 extension 路径和完整的 embedding profile：

export POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_MODEL=provider:embedding-model
export POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_PROFILE_ID=embedding-model-v1
export POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_DIMENSION=1024
export POWERCONTEXT_SERVER_DATABASE_VEC1_EXTENSION=/opt/sqlite-extensions/vec1
powercontext server run

extension 路径必须指向 SQLite loader 可以打开的 library。Server 打开数据库时，PowerContext 会加载并探测该 extension；如果 library 不兼容或版本低于 0.7，启动会失败。

在另一个终端确认初始化后的 Runtime 已报告 vector 和 hybrid search：

powercontext capabilities

如果没有可用的 Vec1，请不要设置 POWERCONTEXT_SERVER_DATABASE_VEC1_EXTENSION。即使没有 embedding model 或 native extension，SQLite full-text search 仍然可用。

CLI Server 连接¶

powercontext 为 Server URL 和 timeout 提供对应的单次命令参数。Token 只能通过环境变量提供，避免出现在 命令行参数中。

Codex 插件¶

Codex Hook 外层超时为十秒。Server 不可用或拒绝鉴权时，恢复、采集和 flush 独立降级，不会阻塞 Codex。 该变量必须存在于启动 Codex 的进程环境中；修改后需要重启 Codex。