Configuration options

Windows support is experimental.

PowerContext reads configuration from environment variables when each process starts. server run loads .env from the current working directory when that file exists. Pass --env-file <path> to select a different file without also merging .env, or pass --no-env-file to disable file loading. For server run, CLI options override process environment variables, process variables override values from the selected file, and defaults apply last. Agent hosts can load their own environment files according to their host-specific rules.

For the configuration-file workflow, including generation, redacted inspection, validation, and launch, see Configure a Server environment. Treat every environment file as a secret-bearing deployment artifact.

service install additionally requires the file to be a regular, non-symlink file owned by the current user with no group or other permissions. The service records its identity and refuses to launch if the file is replaced or its ownership, permissions, or contents change; run service install again after an intentional update.

Atomic Memory

See Use Atomic Memory for creation, search, lifecycle and restoration examples, and offline migration for existing databases.

Restoration previews require an explicit shared signing key. Every process that generates or validates tokens must use the same secret and key ID:

An unset secret never generates a random process key. Changing the secret or key ID invalidates old tokens; preview again. A restoration with a token returns preview_stale on changes instead of reinterpreting the intent. The retry budget does not replay a write whose commit outcome is unknown after a connection failure.

Source processing generates candidates, then enumerates related active memories satisfying permission, tag and retrieval eligibility. Fts enumerates all qualifying matches; vector enumerates all results within its threshold; hybrid combines both. Neither comparison batch size nor token budget truncates the total candidates. Oversized comparison input reduces the batch until every candidate is processed. A single object or complete extraction input that exceeds the budget fails the window without partial publication or cursor advancement. Fallback changes recall evidence and requires an explicit choice; by default errors retain the window for diagnosis and retry.

Atomic Memory has no legacy collection capacity budget or compact operation. MEMORY_MAX_ACTIVE_ENTRIES, MEMORY_MAX_MANIFEST_ENTRIES, MEMORY_MAX_MANIFEST_BYTES and MEMORY_COMPACTION_* settings remain parseable but do not limit new memories or enable compaction. MemoryWriteGate is fail-open and only governs the write decision; it never changes authoritative history. For a hosted decision backend, set MEMORY_WRITE_GATE_PRIVACY_BOUNDARY=hosted_redacted and explicitly select MEMORY_WRITE_GATE_SANITIZER=known_secrets. The sanitizer covers known sensitive environment/Codex values and a bounded set of provider-key prefixes; it is not a general PII or password detector. The sanitizer selection defaults to none, and hosted-redacted composition fails with a named configuration error until one is selected. The existing limit of 32 tags per Artifact still applies. If merged input tags exceed it, the whole merge fails; Source processing also retains the window without partial publication or cursor advancement.

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;
• Windows: %LOCALAPPDATA%\\powercontext.

The default SQLite database is powercontext.db in this directory. Built-in background processors persist intents and scheduling checkpoints in the same database. Existing installations require offline migration.

Server

Server settings use the POWERCONTEXT_SERVER_ prefix.

The recall channel weights are a ratio and apply to Atomic Memory and Topic Memory only after hybrid candidates pass their channel admission floors. Single-channel searches remain unweighted; auto applies the weights only when it selects hybrid search. Atomic Memory excludes zero-weight channels from matched_by and recall-gate relevance. Topic Memory retains their evidence for Topics selected by a positive-weight channel. Scaling both values equally has no effect. Setting one value to 0 excludes that channel from hybrid fusion, but a higher weight cannot restore a candidate rejected before fusion. A zero weight does not disable that channel's retrieval or admission work: vector embeddings may still be generated, and retrieval/admission counts still include the zero-weight channel. A Topic or Atomic Memory Artifact search request that supplies its own fusion parameters replaces the deployment recall weights entirely. The deployment weights apply only when the request does not specify fusion parameters. After normalization, each non-zero channel weight must be at least the smallest normal IEEE 754 binary64 value (2.2250738585072014e-308); smaller values are rejected at startup. Only an explicit 0 disables a channel's fusion contribution. Evaluate weight changes together with recall-gate rounds, semantic admission floors, and historical Topic candidate selection instead of treating the knobs independently. In particular, weighting FTS more heavily can move a Topic's normalized score across POWERCONTEXT_SERVER_RUNTIME_TOPIC_MEMORY_HISTORY_RRF_THRESHOLD (default 70) and change which historical Topics are sent to the planner.

The recall-sufficiency gate is disabled by default. When enabled, the Runtime assesses the first recall's candidate count, family coverage, top-candidate score, and lexical coverage during prepare_context; when it judges the result insufficient, it may expand up to two more rounds and relaxes the semantic-similarity admission floor each round. The assessment calls no model, and expansion reuses the same request's Scope, families, limits, and context budget along with the query vectors already produced. The round-one and round-two similarity floors must stay in decreasing order, or startup fails. Enabling the gate can add search rounds and latency, so evaluate retrieval results and latency on your own data.

When the gate produces a RecallEffort, the relational Runtime adds one observation to pc_recall_effort_daily, keyed by (scope_id, usage_date, policy_id, assessment). Dates use UTC. The additive counters describe committed search rounds, expansion actions, candidate-pool sizes, search-reported additional inference calls, and final byte-budget truncations and drops. The two drop subclasses sum to dropped_items; invalid counts are rejected before persistence. The table contains only its key dimensions and counters, without entry identities, queries, prompts, citations, or content bodies. It is an internal aggregate and is not included in the statistics overview or HTTP/MCP responses.

Recall-effort recording makes one write attempt within POWERCONTEXT_SERVER_RUNTIME_MODEL_USAGE_WRITE_TIMEOUT_SECONDS. A failed write logs a safe diagnostic and preserves the prepared context. Request cancellation waits for the owned transaction's native cleanup before propagating, preserving a shared in-memory SQLite database. A caller-supplied recall_effort_sink replaces the relational recorder; a disabled gate invokes neither. Existing SQLite and OceanBase databases gain the missing relation through the normal additive table-creation path.

Model usage accounting is best-effort and never gates a model call. Each Runtime owns one bounded recorder that accepts a record without any I/O and writes it in an independent short transaction, so a statistics outage, a full queue, or a lock that outlives the record's own budget drops that record with a diagnostic instead of failing the operation that produced it. Already-accepted usage is drained within a bounded wait when an operation completes or statistics are read, and again at shutdown. Contended business writes fail by design once they have waited this long: SQLite admits one writer at a time, so a concurrent writer holding the lock for longer than the configured value makes the waiting business write report database is locked. That is why multi-scope deployments raise POWERCONTEXT_SERVER_DATABASE_BUSY_TIMEOUT_MS; the same lock pressure no longer reaches usage accounting, and usage records are dropped rather than failing the operation that produced them.

Topic Workers enforce a durable allowance per unadvanced Scope Cursor: 3 attempts, 512 reserved provider requests, and 64,000,000 estimated token-capacity units across all retries. A Window admits at most 4,194,304 canonical evidence characters including metadata; nested input is also bounded. Exhaustion preserves Sources, Cursor, Pending, and the same-Scope tail, and stops further provider calls. Flush and restart do not reset it; inspect pc_topic_memory_work_budgets and structured errors for operator remediation.

Topic generation accepts max_tokens, temperature, top_p, top_k, seed, presence_penalty, frequency_penalty, timeout, openai_reasoning_effort, openai_text_verbosity, service_tier, openai_service_tier, anthropic_service_tier, and anthropic_effort as bounded scalar settings. Topic Embedding accepts only dimensions and truncate. For generation with openai-chat:<model>, the sole extra_body exception is {"chat_template_kwargs":{"enable_thinking":false}}, with a strict boolean and no extra keys at either level. Background/hidden-history/native-tool settings and all other extra_body forms disable Topic processing while ordinary inference continues; explicitly configured automatic Topic scheduling fails startup instead. Supported provider prefixes are openai, openai-chat, openai-responses, anthropic, azure, azure-responses, deepseek, and openrouter, plus the local test model; Embedding must also be supported by its SDK adapter. Topic SDK transport retries and automatic continuations are disabled. Non-Topic inference keeps its existing settings behavior.

When the cursor signing secret is unset, a file-backed SQLite Server creates a private key beside its database; other persistent backends create one in the PowerContext user data directory. In-memory SQLite uses a process-local key. Configure the same POWERCONTEXT_SERVER_CURSOR_SIGNING_SECRET on every replica so a cursor remains valid after restart or when the next request reaches another replica. Never expose or rotate this value while issued cursors must remain valid.

Access Control is disabled by default. In enforced mode, API and MCP requests must establish a Principal through the selected Authentication Provider; the liveness and readiness endpoints remain public. The built-in static-bearer Provider accepts Authorization: Bearer <token>. Plain HTTP is trusted only on a loopback address (localhost, ::1, or any address in 127.0.0.0/8). The Server refuses to start when it binds to a non-loopback address while authentication is disabled; either enable authentication, keep the bind on loopback, or, when TLS is terminated upstream or the network is otherwise controlled, set POWERCONTEXT_SERVER_ALLOW_UNAUTHENTICATED_NON_LOOPBACK=true to opt in explicitly. Use TLS before exposing an authenticated Server over a network.

POWERCONTEXT_SERVER_ACCESS_MODE is the only supported switch. disabled bypasses authorization decisions inside the trusted local boundary. enforced enables one policy enforcement point plus Binding and audit behavior. Authorization defaults to the built-in implementation and can be replaced through create_server_app(access_control=...); Authentication is supplied through create_server_app(authentication_provider=...). Without an injected Authentication Provider, the Server accepts only the legacy AUTH_TOKEN fallback and bootstraps its fixed server-token Principal as a built-in administrator. Startup fails when neither is available. The old AUTH_ENABLED=true plus AUTH_TOKEN configuration maps automatically to ACCESS_MODE=enforced.

Authentication establishes a Principal; Access Control decides what that Principal may do. Principal IDs are deployment-wide unique, non-reused identifiers; description is display metadata and is not part of identity. The built-in static token always represents one service Principal, so it cannot distinguish user A from user B. The compatibility token materializes explicit Server and per-scope roles for that Principal. Inject the deployment Authentication Provider and corresponding AccessControlService when different users or groups need different access.

Source-driven background Memory, Topic Memory, Experience, and Profile processing use the service Principal selected by ACCESS_BACKGROUND_PRINCIPAL_ID, falling back to the fixed static Principal. That Principal must have scope.contribute for each processed scope and write permission on existing Artifacts it changes. New entries, Artifacts, and Candidates retain its ownership or owner attestation in the same transaction as processing completion. An enforced deployment with background capabilities fails startup if its identity or authorization provider cannot be reconstructed in a child process, even when automatic schedules are disabled: accepted work still needs recovery. The built-in provider supports this reconstruction. Injected providers and model objects remain usable by synchronous SDK/Server operations with background capabilities disabled (ARTIFACT_PROCESSING_FAMILIES=[]).

Dream reconstructs the original requester's current permissions inside Experience/Skill Workers, and Candidate ownership remains with that requester. Background service Principal permissions do not replace that identity. An OceanBase split deployment can declare ARTIFACT_PROCESSING_FAMILIES=["experience","skill"] on a model-free API process and declare the same capabilities with model configuration on the background process; automatic schedules may reference only declared Families. SQLite uses all. Dream pins its model identity on first execution, and disabling automatic schedules does not prevent accepted explicit Dream requests from completing.

SDK workers without a Server identity do not require Server authorization dependencies. Built-in background workers use the built-in Source definitions. A custom Source registry requires custom processing bindings for every enabled family, or disabling built-in background families with ARTIFACT_PROCESSING_FAMILIES=[]; otherwise startup fails before accepting work. Turning off schedules alone is insufficient because explicit requests still start workers. Custom Source registries remain available to synchronous SDK contexts and API-only composition.

The authenticated /metrics endpoint exposes powercontext_server_artifact_processing_* observations with only a family label: Worker capacity, ready/retry queues, unacknowledged Scopes, discovery and invocation duration, completions, failures, and timeouts. Unacknowledged counts reflect the latest discovery; counters reset with the Supervisor instance.

The extraction object in GET /v1/capabilities separates configuration, background execution, and local observations. Reading this snapshot does not query the database or call a model, and does not produce an overall health verdict. powercontext capabilities prints the same facts. Missing diagnostics print unavailable, a null supervisor role prints absent, and unknown values print unknown. Success and failure times are historical observations, not a current health verdict. --json returns the Server payload unchanged.

• configuration is configured when a local extraction model or custom pipeline is assembled, or a local Memory worker is registered. It is unconfigured when none is available. Registration does not verify credentials or connectivity. External execution reports unknown.
• background.location is local, external, or none. The local Supervisor's role (leader or standby) is separate from its state (running, degraded, or stopped); standby is normal. A worker crash can coexist with a running Supervisor that arranges retries. automatic_processing_enabled=false still permits explicit work. External execution has unknown state and schedule; no running local Supervisor means a null role.
• observation.since marks the start of this Runtime's local observation window, including its child Memory workers. status=unverified means no execution outcome or control failure has been observed; observed means evidence exists. last_success_at records a successful nonempty flush or acknowledged worker invocation. last_failure records a safe code, stage, and occurred_at, such as model_timeout at inference or worker_crash at worker. Generic failures retain the observing boundary (flush or worker) without assuming a model failure.

Success and failure records are independent: Scope B succeeding does not clear Scope A's failure or prove its recovery. A historical failure also does not mean an incident is still unresolved. Observations reset on Runtime restart and do not prove model connectivity or remote worker health. Use structured logs for Scope-specific failures and retries, and the existing metrics for queue and progress observations; local ready counts are not a global Source backlog.

Remote and multi-user deployments must use enforced. In that mode, HTTP, MCP, and metrics share one Server PEP. /v1/access/me reports the server/scope/artifact Resource Kinds, Provider batch/list/relationship capabilities and Artifact Family profiles. Managed Skill export and installation do not introduce separate Access actions: the recipient first needs artifact.read on the logical Skill identity, then chooses whether and how to install an exact Revision.

The built-in Access schema uses the configured SQLite, seekdb, or OceanBase backend, but remains Server-owned rather than becoming a Runtime domain. A custom deployment can inject an AccessControlService into create_server_app. CasbinAuthorizationProvider is the included writable external adapter: it evaluates the fixed action vocabulary in embedded Casbin while using the canonical Binding Store as its persistent adapter, so it supports point/batch checks, safe resource filters, create/revoke, expiry, and CAS without a second policy shadow. Pass that provider as both the decision provider and relationships, and retain the relational repository as the audit store.

AuthZenAuthorizationProvider is an included decision-only adapter for the OpenID AuthZEN Authorization API 1.0 evaluation and evaluations endpoints. Configure its capabilities with multi_requirement_check=true, relationship_management=false, and safe_resource_filtering=false; self-service Binding mutation and authorized resource listing then return 503 instead of claiming an unsafe capability. The adapter accepts HTTPS endpoints or loopback HTTP, rejects credentials embedded in URLs, and does not expose PDP response bodies or errors. An authentication middleware must still bind an opaque PrincipalRef; scope_id is only a resource partition and never establishes identity.

The Python Client and CLI apply the matching rule for general outbound requests: a configured unencrypted http:// Server URL is accepted only for loopback hosts. The explicit remote Skill Receiver PoC exception is documented below. Code whose http:// base URL is only a routing label for a transport that is secure in practice, such as an in-process ASGI app, Unix-domain socket, or TLS-terminating proxy, must supply its own http_client and pass trust_transport_security=True explicitly. See Deploy the Server for a safe Docker and remote-access setup.

By default, the Server treats its startup directory as the workspace and exposes two writable local project targets: <workspace>/.agents/skills for Codex and <workspace>/.claude/skills for Claude Code. Missing directories are harmless and are created only by an explicit publication operation. Set POWERCONTEXT_SERVER_WORKSPACE once for systemd, containers, or other launchers whose working directory is not the project.

Configure POWERCONTEXT_SERVER_PUBLIC_URL when remote Skill Receivers should connect through a stable externally reachable origin. Enrollment commands may otherwise use the remote CLI's configured Server URL.

For a first-phase PoC on a protected internal test network, direct HTTP requires explicit consent on both sides. Set POWERCONTEXT_SERVER_ALLOW_INSECURE_HTTP=true, advertise an http:// POWERCONTEXT_SERVER_PUBLIC_URL, and bind the listener to an address reachable by the target. The enrollment command must include remote-enroll --allow-insecure-http. Without the Server setting, the remote endpoints reject non-loopback HTTP. Without the Receiver option, the CLI rejects the URL before transmitting the one-time enrollment code. The permission is stored in the owner-only Receiver configuration so remote-watch and its systemd user service keep the same policy without embedding credentials or extra flags in the unit. This switch adds no TLS, network isolation, or protection against interception: do not use it on the public Internet or an untrusted network, and prefer HTTPS for persistent deployments.

export POWERCONTEXT_SERVER_HTTP_HOST=0.0.0.0
export POWERCONTEXT_SERVER_PUBLIC_URL=http://powercontext.internal.example:8765
export POWERCONTEXT_SERVER_ALLOW_INSECURE_HTTP=true
export POWERCONTEXT_SERVER_ALLOW_UNAUTHENTICATED_NON_LOOPBACK=true
powercontext server run

# On the target project:
powercontext --server-url http://powercontext.internal.example:8765 \
  skill remote-enroll --workspace "$PWD" --install-service --allow-insecure-http

The non-loopback opt-in in this example is independent of the Receiver transport exception: it acknowledges that all Server routes on this listener are reachable without the Server-wide bearer token. Prefer enabling authentication or terminating TLS in front of a loopback-bound Server whenever the deployment permits it.

Handoff Report API routes are independently enabled by default. See Use Handoff Report for selection, inspection, and export.

The Artifact Processing Supervisor is enabled by the default all role. OceanBase deployments may run api and background separately; powercontext server run --role background starts no HTTP, MCP, or Dashboard listener, and multiple background candidates use the database Lease to elect one active Leader. SQLite and embedded seekdb support only the single-process all role. Automatic Topic Memory waves remain disabled until a positive interval is set; explicit flush work remains recoverable regardless of that interval. Topic workers need file-backed SQLite: configuring a generation model with an in-memory SQLite database is rejected before processing is advertised. Use a persistent POWERCONTEXT_SERVER_DATABASE_URL, such as sqlite+aiosqlite:////srv/powercontext/runtime.db. Memory, Topic Memory, Experience, and Profile all use the Supervisor. OceanBase permits their schedules in split roles. SQLite and embedded seekdb retain one all host. Every Family has its own quota and timeout in both modes; spare quota is not shared. Disabling automatic admission preserves already accepted requests. The API and background instances must agree on mode, registered Families and trigger capabilities. Model resources are only required by workers. Changing modes requires coordinated offline migration; mixed modes cannot start. Conflicting explicit old/new configuration aliases fail startup; equal values are accepted.

Normal Runtime startup initializes and recovers the configured search indexes. Topic Workers reuse that database without rebuilding the unrelated Memory/Experience search projections for each Window; Topic index validation and publication guards still apply. If an empty database is reconfigured to another Topic retrieval shape or embedding profile, reopen existing Runtimes with the same configuration: stale Runtimes reject Topic search, exact get, and current-head browsing with a retrieval-shape error instead of reading another vector space.

Normal Runtime startup initializes and recovers the configured search indexes. Topic Workers reuse that database without rebuilding the unrelated Memory/Experience search projections for each Window; Topic index validation and publication guards still apply. If an empty database is reconfigured to another Topic retrieval shape or embedding profile, reopen existing Runtimes with the same configuration: stale Runtimes reject Topic search, exact get, and current-head browsing with a retrieval-shape error instead of reading another vector space.

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 built-in reranker is an LLM listwise reranker, not a dedicated cross-encoder protocol. By default it reuses the generation model and its provider settings. Set POWERCONTEXT_SERVER_INFERENCE_RERANK_MODEL to give that LLM operation an independent model, base URL, headers, settings, timeout, and request limit.

The same configured generation model gates explicit Experience generation, managed Skill generation, and semantic Skill fork/evolution. Exact external Skill import and complete package upload do not use a model: PowerContext validates and stores the canonical package bytes, then creates a pending Candidate with the same package digest. Without a generation model, semantic generation returns a capability error before persisting a Candidate; Review, package inspection and download, exact import, usage recording, and external Skill scan/list/resolve continue to work.

Experience incubation has its own Supervisor binding and persisted Source cursor. Each invocation inspects a finite window controlled by SOURCE_WINDOW_LIMIT 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 to an Agent target, or execute anything. Memory and Experience keep independent scheduling intervals, Worker quotas, and business cursors. Unsetting an interval stops new automatic admission for that Family while preserving accepted work. See Create and review an Experience for setup and verification steps.

Agent Skill targets

The zero-configuration flow uses the Codex and Claude Code project folders under the workspace. Provide a JSON override only for custom paths, user-level targets, environment compatibility facts, or to explicitly disable local discovery. For a basic JSON shape and verification flow, see Configure Agent Skill targets. A compatibility-aware override looks like:

export POWERCONTEXT_SERVER_EXTERNAL_SKILLS='{
  "host_id": "workstation-1",
  "targets": [
    {
      "target_id": "codex-project",
      "agent_kind": "codex",
      "installation_scope": "project",
      "path": "/srv/project/.agents/skills",
      "allow_managed_publish": true,
      "environment": {
        "operating_system": "linux",
        "architecture": "x86_64",
        "commands": {"python": "3.13.2", "bash": "5.2"},
        "network_policy": "restricted",
        "writable_roots": ["workspace"],
        "dependency_install_policy": "denied",
        "environment_names": ["CI"]
      }
    },
    {
      "target_id": "claude-project",
      "agent_kind": "claude_code",
      "installation_scope": "project",
      "path": "/srv/project/.claude/skills",
      "allow_managed_publish": true
    }
  ]
}'

Setting POWERCONTEXT_SERVER_EXTERNAL_SKILLS replaces both automatically generated project targets in full; use {"host_id": null, "targets": []} to disable local discovery and publication. Target IDs must be unique. agent_kind supports codex and claude_code; installation scopes are user, project, and plugin. PowerContext scans only the immediate Skill package directories under default or explicit targets; it does not infer a user home directory, install packages, or grant execution authority. Custom targets default allow_managed_publish to false; when true, an explicit publication operation may safely create or update an approved managed Skill in that target. Publication materializes the exact reviewed package, including scripts and references, without executing it or injecting a sidecar into the package. Unpublication succeeds only for an intact package whose binding and tree digest still match; local drift and foreign content remain untouched. Publication cannot submit an arbitrary path or overwrite a foreign or modified package. The host_id, locator, and registration are local-environment state, not a cross-host contract. Existing codex_roots configuration remains accepted as a Codex-only compatibility form; new configuration should use targets.

The optional environment object contains only observed, secret-free compatibility facts. Command values are version labels, and environment_names records names only, never values. PowerContext does not probe or execute package scripts to construct this profile. When it is absent, packages containing scripts report unknown compatibility; when present, the Skills Library compares known script interpreters with the observed command names and returns a reasoned assessment. The assessment does not grant network, filesystem, dependency-install, or environment access.

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 Trace with Langfuse for a backend that authenticates the exporter through OTEL_EXPORTER_OTLP_HEADERS.

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 and SQLite vector search

Vector search requires all three embedding identity variables: model, stable profile ID, and positive dimension. Normalization defaults to unit; timeout and batch size are optional controls. SQLite vector and hybrid search use the bundled sqlite-vec extension. The Server probes it when opening the database, and startup fails if the installed library is incompatible with the platform or SQLite build. Full-text search remains available without an embedding profile. For configuration and capability verification, see Configure vector search.

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.

Agent integrations

For installation, connection, authentication, and environment variables, use the guide for your integration.