Configuration¶

PowerContext reads configuration from environment variables when each process starts.

User data¶

POWERCONTEXT_HOME overrides the directory used by the installed Server:

export POWERCONTEXT_HOME=/srv/powercontext

Without an override, the default is:

• Linux: $XDG_DATA_HOME/powercontext, or ~/.local/share/powercontext;
• macOS: ~/Library/Application Support/powercontext.

The default SQLite database is powercontext.db in this directory. Scheduled processing uses scheduler.db in the same directory.

Server¶

Server settings use the POWERCONTEXT_SERVER_ prefix.

Static bearer authentication is disabled by default. When enabled, API and MCP requests must include Authorization: Bearer <token>; the liveness and readiness endpoints remain public. Plain HTTP should remain on a loopback address. Use TLS before exposing an authenticated Server over a network.

Example with a controlled SQLite path and scheduled extraction:

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

Provider credentials, such as OPENAI_API_KEY, are read by the configured inference provider. Do not place secrets in command-line arguments, documentation, or Memory. Replace provider:model-name with a model identifier supported by Pydantic AI. Scheduled extraction requires both a generation model and POWERCONTEXT_SERVER_RUNTIME_SCHEDULE_SECONDS. An explicit Memory write does not require either.

The default coding extraction profile keeps cross-task work context such as preferences, decisions, constraints, expensive facts, and unfinished progress. Select conversation when the product must preserve independently answerable personal facts, relationships, events, exact dates, lists, and historical states from dialogue evidence:

export POWERCONTEXT_SERVER_RUNTIME_MEMORY_EXTRACTION_PROFILE=conversation

The profile affects future Source processing only. It does not reinterpret existing Memory revisions.

Enable answer-oriented Memory reranking when broad Hybrid recall is more important than the latency and token cost of one additional structured generation request:

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

Reranking is disabled by default. When enabled, the Runtime retrieves and fuses the configured candidate pool, then uses the generation model at temperature zero to select no more than the search request's final limit. It does not change stored Memory or indexes. Provider and structured-output failures remain visible as inference errors; disable reranking when search must remain independent of model availability. See RFC 0080 for the algorithm, concurrency, and API boundaries.

The same configured generation model gates explicit Experience generation, managed Skill generation and evolution, and external Skill import or fork. Without it, these operations return a capability error before persisting a Candidate. Candidate Review, exact reads, and external Skill scan/list/resolve continue to work.

Experience incubation is a separate APScheduler job with its own persisted Source cursor. Enable it with:

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

Each activation inspects a fixed window of at most 32 Sources and exposes only Content Sources whose metadata contains "kind": "task-outcome" to the model. It creates pending Experience Candidates in the Review Inbox; it does not approve them, place them in PreparedContext, create a managed Skill, export it for Codex, or execute anything. The Memory and Experience jobs share the APScheduler sidecar under POWERCONTEXT_HOME, but keep independent job identities and business cursors. Unsetting one interval removes only that job.

External Codex Skills¶

Configure host-local roots as one JSON value:

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

Root IDs must be unique. Supported installation scopes are user, project, and plugin. PowerContext scans only the immediate Skill package directories under these explicit roots; it does not infer a home directory, install packages, or grant execution authority. The host_id, locator, and registration are local-environment state, not a cross-host or cross-Agent contract.

The Server always creates non-recording OpenTelemetry request context so X-PowerContext-Request-ID can be derived from the inbound span. To enable recording and export for a CLI-managed Server, install powercontext[cli,server,tracing-otlp], enable tracing, and configure standard OpenTelemetry variables such as OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_HEADERS, and OTEL_SERVICE_NAME. Programmatic Server integrations that do not use the powercontext command may omit the cli extra.

Enabling tracing also produces spans for the generation and embedding calls that PowerContext constructs, without recording prompts, model responses, Memory content, or vectors. See Trace with Phoenix for a working configuration and the one documented exception.

To use OceanBase, provide its URL through your environment or secret manager:

export POWERCONTEXT_SERVER_DATABASE_KIND=oceanbase
export POWERCONTEXT_SERVER_DATABASE_URL="$OCEANBASE_URL"

The URL must use the mysql+aoceanbase driver, include an explicit port and database, and set charset=utf8mb4. The tenant must use MySQL compatibility mode.

Embeddings¶

Embedding search is enabled only when all three identity fields are set:

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

Replace the example values with the selected provider model, a stable profile ID, and that model's dimension.

Optional settings are POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_NORMALIZATION and POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_TIMEOUT_SECONDS.

Embedding normalization defaults to unit.

SQLite Vec1¶

SQLite vector and hybrid search additionally require a SQLite Vec1 0.7 or newer loadable extension. PowerContext does not download, build, or update this native library. Obtain it for the Server's operating system and architecture, then set its path together with the complete 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

The extension path must identify a library that the SQLite loader can open. PowerContext loads and probes the extension when the Server opens the database; startup fails if the library is incompatible or older than 0.7.

In another terminal, confirm that the initialized runtime reports vector and hybrid search:

powercontext capabilities

If Vec1 is unavailable, leave POWERCONTEXT_SERVER_DATABASE_VEC1_EXTENSION unset. SQLite full-text search remains available without an embedding model or native extension.

CLI Server connection¶

Equivalent one-off flags are available for the Server URL and timeout on powercontext. The token is accepted only through the environment so it does not appear in command-line arguments.

Codex plugin¶

The outer Codex hook timeout is ten seconds. Recall, capture, and flush fail independently and never block Codex when the Server is unavailable or rejects authentication. The variable must be present in the environment that starts Codex; restart Codex after changing it.