README.md

PowerContext for Bub

evaluation

This package connects Bub to a running PowerContext Server through the public Python client. It adds three tools:

• powercontext.remember stores one durable decision, preference, constraint, or procedure.
• powercontext.search searches durable memory.
• powercontext.context prepares bounded context for a question.

Before each model call, the plugin also prepares relevant context and adds it as host-supplied historical evidence. Automatic trajectory capture is opt-in. When enabled, the plugin captures the initial task and completed LLM and tool events as bounded Content Sources. It periodically flushes those Sources through the Memory pipeline so later model steps in the same Bub run can recall earlier findings. Provider-hidden reasoning is never available to the hook and is not captured.

Configuration

The plugin uses Bub's Pydantic settings extension. Configuration can live in the powercontext section of Bub's configuration file:

powercontext:
  base_url: http://127.0.0.1:8000
  capture_events: true
  capture_checkpoint_every: 5

Environment variables use the POWERCONTEXT_BUB_ prefix and take precedence over file values. Values are parsed and validated by Pydantic before the plugin starts.

Variable	Default	Purpose
POWERCONTEXT_BUB_BASE_URL	http://127.0.0.1:8000	PowerContext Server URL
POWERCONTEXT_BUB_API_TOKEN	unset	Bearer token for a Server that requires authentication
POWERCONTEXT_BUB_ALLOW_INSECURE_HTTP	false	Explicitly allow non-loopback HTTP for recall, capture, and tools; HTTPS certificate validation stays enabled
POWERCONTEXT_BUB_SCOPE_ID	unset	Explicit Scope resolved and validated by the Server before use
POWERCONTEXT_BUB_TIMEOUT	10	Client timeout in seconds
POWERCONTEXT_BUB_MAX_BYTES	8000	Maximum prepared-context size
POWERCONTEXT_BUB_CONTEXT_ASSEMBLY	unset	JSON object selecting prepared-context families and output options
POWERCONTEXT_BUB_CAPTURE_EVENTS	false	Capture completed Bub events as Content Sources
POWERCONTEXT_BUB_CAPTURE_CHECKPOINT_EVERY	5	Flush Memory after this many captured events
POWERCONTEXT_BUB_CAPTURE_MAX_BYTES	8192	Maximum UTF-8 bytes stored for one captured event
POWERCONTEXT_BUB_CAPTURE_LOG	unset	Optional JSONL evidence path; records metadata but not event content
POWERCONTEXT_BUB_TRUST_TRANSPORT_SECURITY	false	Vouch for a plaintext non-loopback BASE_URL on an operator-controlled network (for example a private Compose bridge); otherwise such URLs are refused

PowerContextSettings(allow_insecure_http=True) also permits non-loopback HTTP. Transport settings resolve from constructor values, host environment, common POWERCONTEXT_CLIENT_SERVER_URL / POWERCONTEXT_CLIENT_ALLOW_INSECURE_HTTP, then the bub entry in ~/.config/powercontext/clients.json (overridden by POWERCONTEXT_CLIENT_CONFIG_FILE). A host value of false overrides common true. Saved consent applies only to its saved Server URL and is not reused when the URL changes.

The plugin never derives a Scope ID from the current directory, Git metadata, or a workspace path. It asks the Server to resolve the configured explicit Scope first, then an opaque stable binding key derived from Bub's workspace identity, and finally the Server default. Only the real Scope returned by the Server is cached and used for recall, capture, and tools.

Captured tool arguments redact values under credential-like keys. Known credential environment values are also removed from serialized event content. Keep the PowerContext scope and optional capture log protected because normal tool output can still contain sensitive project data.

Install the package together with PowerContext and Bub:

uv pip install -e . -e integrations/bub

Legacy context retrieval remains available with powercontext==0.2.0 when context_assembly is unset. Text assembly requires a core and Server that support it; install the core and plugin together from the same checkout using the command above. On an older core, configuring assembly raises an explicit upgrade message at startup.