PowerContext Go

PowerContext Go requires Go 1.27.0 or newer. Its current alignment target is the formal PowerContext v0.1.0 release at 7b736206a53a6de6f43d4b517893ee1a80e7183d; the frozen Python v0.0.2 snapshot remains a historical regression fixture, not the current acceptance target. The implementation uses Go-native domain types, lifecycle ownership, concurrency, persistence, transports, and release packaging.

module github.com/ob-labs/powercontext-go
parity target powercontext-v0.1.0 7b736206a53a6de6f43d4b517893ee1a80e7183d
historical fixture python-v0.0.2 3a6cb0151670eaff7dc0293466edd673124e80da

The HTTP source of truth is openapi/powercontext.yaml. Generated code under api/v1 is never edited by hand. Compatibility evidence lives under test/conformance: the v0.1.0 release inventory contains 812 Python test cases in 132 files, alongside the immutable historical v0.0.2 fixture. The generated parity-inventory.json is the current case-by-case mapping: mapped cases resolve to specific evidence, and pending cases are not compatibility claims.

This table describes the currently implemented and evidenced boundary. The upstream Python release is the alignment target; it is not a PowerContext Go binary release.

See docs/release/INSTALL.md for the exact release identity, configuration, upgrade, transport, and host-operation contract.

The next unpublished release candidate has one explicit two-root integration inventory. Standard and Full archives contain exactly Codex and WorkBuddy; edition differences remain limited to their existing native inference assets.

The archived integration content consists of reviewed source, manifests, lock files, and tracked executable bundles. It never carries an active credential, prompt, source or Memory content, raw scope ID, or local database path. Authorization remains a runtime environment reference. A checkout-local consumer result is not archive evidence.

• source, artifact, trigger, and inference are lifecycle-free public extension contracts; artifact/{memory,experience,skill,handoff} contains the public typed Artifact families.

• internal/{review,contextpack,handoffreport,stats,work} contains product domains that are shared by the Server but are not part of the embedded Go SDK surface.

• internal/runtime owns admission, Scope boundaries, same-Scope write serialization, scheduled processing, and application use cases.

• client and server are public remote and process facades.

• internal contains product-only domains and concrete adapters: SQL, providers, scheduler, endpoints, HTTP, MCP, dashboard, CLI, and observability. Native seekDB and sqlite-vec ownership lives below internal/sqlstore.

• integrations contains the supported Codex and WorkBuddy release roots plus historical adapter source. Only Codex and WorkBuddy are packaged, installed, or exercised as active host integrations.

• evaluation contains the deployment-neutral Codex/SQLite evaluation control plane. It is maintained and tested in this repository, but is neither embedded in the Go binary nor a Go release-runtime requirement.

• test contains conformance, differential, and process-level suites; tools contains generators and release tooling.

• benchmark/locomo contains operator-facing LoCoMo configuration and result space; its Go runner lives in tools/locomo, with deterministic internals in internal/benchmark/locomo.

The deliberate public Go packages are checked against the approved pre-release baseline under test/api-compat. make api-compat permits compatible additions but rejects removed or incompatibly changed exported identifiers. Updating the baseline with make api-baseline requires review of the compatibility impact; the baseline is a pre-release change-control gate, not a declaration of Go v1 stability before the first release.

There is intentionally no common, utils, generic repository layer, or DI container. Shared infrastructure exists only where it has one clear owner—for example, privacy-safe log/slog setup under internal/observability/logging.

This is a Go-primary monorepo: Python and TypeScript host assets and the evaluation control plane remain tracked, licensed, and tested, but GitHub language statistics deliberately exclude them from the primary Go product classification. The supported product matrix is Codex, WorkBuddy, and SQLite. Other adapter and backend source is historical and does not expand that matrix.

See docs/architecture/README.md for the full directory map and dependency rules.

See CONTRIBUTING.md for the supported Go policy, change boundaries, validation requirements, and pull request contract.

The standard build uses CGO and statically embeds the same sqlite-vec 0.1.9 vec0 implementation as the Python runtime:

make check
make lint
make contract-test
make unit-test
make e2e-test
make build

Run the server with the frozen defaults:

./bin/powercontext server run

Server configuration uses POWERCONTEXT_SERVER_*; remote CLI configuration uses POWERCONTEXT_CLIENT_SERVER_URL, POWERCONTEXT_CLIENT_API_TOKEN, and POWERCONTEXT_CLIENT_TIMEOUT. The full local-embedding build additionally requires the native tokenizer and ONNX Runtime assets described in docs/release/INSTALL.md.

Run powercontext config init --non-interactive to create a managed local environment file. Inspect it without disclosing credential values with powercontext config show --env-file .env, and validate syntax, persistent storage paths, and Server settings with powercontext config validate --env-file .env. SQLite is the only supported database. Configuration that selects seekDB, OceanBase, or another database is rejected before storage is opened.

Plain HTTP is trusted only on loopback (localhost, ::1, or any address in 127.0.0.0/8). The Server refuses an unauthenticated non-loopback bind by default. For remote access, enable bearer authentication and terminate TLS in front of the Server; controlled networks or deployments with upstream TLS may instead opt in explicitly with POWERCONTEXT_SERVER_ALLOW_UNAUTHENTICATED_NON_LOOPBACK=true.

For an authenticated non-loopback bind behind a TLS terminator, replace the example token before starting the Server:

POWERCONTEXT_SERVER_AUTH_ENABLED=true \
POWERCONTEXT_SERVER_AUTH_TOKEN='replace-with-a-strong-token' \
./bin/powercontext server run --host 0.0.0.0

The Go Client likewise rejects plaintext HTTP to a non-loopback Server unless the caller supplies its own http.Client and explicitly sets TrustTransportSecurity for a separately secured transport.

Useful verification targets:

make lint-fix
make license-check
make docs-test
make test-sqlite
make test-race
make test-full TOKENIZERS_LIB_DIR=/path/to/tokenizers/lib

The lint targets install the pinned golangci-lint release under .tools/bin; its embedded gofumpt and goimports versions are therefore the same locally and in CI. No mutable global linter installation is used.

If a newly added source file is missing the standard Apache-2.0 header, repair all eligible files and immediately recheck them with one command:

make license-fix

The checked file types and deliberate generated/vendor exclusions are defined in .licenserc.yaml. SkyWalking Eyes is version-pinned by the Make target and does not modify prompt text, fixtures, lock files, or generated Go contracts.

The Go-native LoCoMo benchmark uses the same runtime, database, providers, and frozen dataset contract as Python:

go run ./tools/locomo inspect --env-file benchmark/locomo/.env.example
go run ./tools/locomo run --env-file .env --run-id locomo-smoke \
  --conversation-limit 1 --question-limit 5

See benchmark/locomo/README.md for resumable ingestion, reranking, Source expansion, and independent rejudging.

Read AGENTS.md before changing package boundaries, persistence formats, lifecycle ownership, or generated contracts.