powercontext-go

module

v0.1.0 Latest Latest Go to latest Published: Sep 2, 2026 License: Apache-2.0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/ob-labs/powercontext-go

Links

Open Source Insights

README ¶

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 and generated operation tables are 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.

Alignment and support matrix

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.

Surface	Current evidence	Pre-WP6 acceptance boundary
Upstream release identity	`powercontext-v0.1.0` at `7b736206a53a6de6f43d4b517893ee1a80e7183d`; the generated case-by-case inventory covers 812 cases in 132 files.	The exact target, distribution digests, fixtures, traceability rules, and generated inventory are checked by the release-contract workflow.
Go Server, SDK, CLI, and OpenAPI	Go-native implementation with `openapi/powercontext.yaml` as the authoritative HTTP contract.	SQLite is the only database accepted before WP6.
Codex and WorkBuddy	Installed integrations call the running Go Server through HTTP or MCP; their service-chain evidence is a required `Pre-WP6 host adapters` check.	These are the only host integrations counted toward WP6 acceptance.
Evaluation	The Codex/SQLite evaluation control plane is executable and independently checked.	It is WP5 evidence, not evidence for every retained host adapter.
Retained adapters	Other maintained adapters retain their own executable `Post-WP6 retained host adapters` CI evidence.	Bub, Claude Code, DSH, Hermes, LangGraph, OpenClaw, OpenCode, and Pi are P3 work and are not WP6 acceptance evidence.
seekDB and OceanBase	Existing code and jobs remain useful backend-plan evidence.	Feature parity, migrations, packaging, license/SBOM work, and release reconciliation are final P4 work.

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

Repository shape

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 maintained host-native adapters. They communicate only with the Go Server and are auxiliary monorepo assets rather than Go binary implementation languages. Before WP6 acceptance, the primary host scope is Codex and WorkBuddy only; all other retained hosts are P3 work.
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 pre-WP6 acceptance matrix is Codex, WorkBuddy, and SQLite. Retained host adapters expand after WP6; seekDB and OceanBase remain the final backend-alignment scope.

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.

Build and verify

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 remains the zero-dependency default. seekDB and OceanBase installation and release guidance remain deferred to the final P4 backend-alignment scope.

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 pi-test
make docs-test
make test-race
make test-full TOKENIZERS_LIB_DIR=/path/to/tokenizers/lib
POWERCONTEXT_TEST_OCEANBASE_URL='mysql+aoceanbase://root%40tenant:password@127.0.0.1:2881/powercontext?charset=utf8mb4' \
  make test-oceanbase-live

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 OceanBase target requires a dedicated disposable MySQL-mode database. It verifies tenant and charset negotiation, the complete core and optional Report schemas, Source cursor CAS, and Handoff Report Activity allocation against the real server rather than a SQL mock.

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.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
api
v1 Package v1 contains generated PowerContext HTTP wire types and operation descriptors.	Package v1 contains generated PowerContext HTTP wire types and operation descriptors.
artifact Package artifact defines immutable revisions, exact references, lineage, and the public persistence contracts shared by Artifact families.	Package artifact defines immutable revisions, exact references, lineage, and the public persistence contracts shared by Artifact families.
experience Package experience implements the reviewed Experience Artifact family.	Package experience implements the reviewed Experience Artifact family.
experience/prompts Package prompts owns the frozen Experience inference instructions.	Package prompts owns the frozen Experience inference instructions.
handoff Package handoff implements temporary and durable Handoff lifecycles.	Package handoff implements temporary and durable Handoff lifecycles.
handoff/prompts Package prompts owns the frozen Handoff inference instructions.	Package prompts owns the frozen Handoff inference instructions.
memory Package memory implements the Memory Artifact family and deterministic retrieval behavior.	Package memory implements the Memory Artifact family and deterministic retrieval behavior.
memory/prompts Package prompts owns the frozen Memory inference instructions.	Package prompts owns the frozen Memory inference instructions.
skill Package skill implements managed Skills and host-native external Skill registration.	Package skill implements managed Skills and host-native external Skill registration.
skill/prompts Package prompts owns the frozen managed-Skill inference instructions.	Package prompts owns the frozen managed-Skill inference instructions.
client Package client provides the public PowerContext HTTP client.	Package client provides the public PowerContext HTTP client.
cmd
powercontext command Command powercontext is the PowerContext server and command-line client.	Command powercontext is the PowerContext server and command-line client.
inference Package inference defines provider-neutral generation, embedding, token, and usage contracts.	Package inference defines provider-neutral generation, embedding, token, and usage contracts.
internal
benchmark/locomo Package locomo owns the deterministic, credential-free boundary of the LoCoMo benchmark.	Package locomo owns the deterministic, credential-free boundary of the LoCoMo benchmark.
benchmark/locomo/prompts Package prompts owns the frozen LoCoMo benchmark instructions.	Package prompts owns the frozen LoCoMo benchmark instructions.
cli Package cli implements the powercontext command tree.	Package cli implements the powercontext command tree.
contextpack Package contextpack selects and renders bounded, explicitly untrusted historical context.	Package contextpack selects and renders bounded, explicitly untrusted historical context.
endpoint Package endpoint maps generated wire operations to domain applications and owns stable wire error translation.	Package endpoint maps generated wire operations to domain applications and owns stable wire error translation.
handoffreport Package handoffreport implements the optional Project catalog, independent Activity journal, Workspace bindings, and deterministic Handoff reports.	Package handoffreport implements the optional Project catalog, independent Activity journal, Workspace bindings, and deterministic Handoff reports.
httpapi Package httpapi provides the HTTP transport and middleware adapters.	Package httpapi provides the HTTP transport and middleware adapters.
jcs Package jcs provides RFC 8785 canonical JSON after recursive Unicode NFC normalization.	Package jcs provides RFC 8785 canonical JSON after recursive Unicode NFC normalization.
mcpapi Package mcpapi exposes the curated Agent-facing MCP operation subset.	Package mcpapi exposes the curated Agent-facing MCP operation subset.
modelprovider Package modelprovider contains provider-specific inference adapters.	Package modelprovider contains provider-specific inference adapters.
observability/logging Package logging configures slog, stable operation fields, context bindings, and privacy-preserving redaction.	Package logging configures slog, stable operation fields, context bindings, and privacy-preserving redaction.
observability/metrics Package metrics records bounded-cardinality transport, application, and inference measurements.	Package metrics records bounded-cardinality transport, application, and inference measurements.
observability/tracing Package tracing propagates and records transport, application, and inference traces.	Package tracing propagates and records transport, application, and inference traces.
review Package review implements family-neutral Artifact Candidate review.	Package review implements family-neutral Artifact Candidate review.
runtime Package runtime composes built-in domain services and owns scope, operation, scheduler, readiness, and resource lifecycles.	Package runtime composes built-in domain services and owns scope, operation, scheduler, readiness, and resource lifecycles.
scheduler Package scheduler owns persisted interval scheduling and worker coordination.	Package scheduler owns persisted interval scheduling and worker coordination.
sqlstore Package sqlstore contains shared relational transactions and repositories.	Package sqlstore contains shared relational transactions and repositories.
sqlstore/oceanbase Package oceanbase implements the OceanBase relational profile and indexes.	Package oceanbase implements the OceanBase relational profile and indexes.
sqlstore/seekdb Package seekdb loads and owns the embedded seekDB runtime used by the SQL store.	Package seekdb loads and owns the embedded seekDB runtime used by the SQL store.
sqlstore/sqlitevec Package sqlitevec statically embeds the sqlite-vec v0.1.9 amalgamation used by the Python v0.0.2 runtime.	Package sqlitevec statically embeds the sqlite-vec v0.1.9 amalgamation used by the Python v0.0.2 runtime.
stats Package stats defines scoped product inventory and usage statistics.	Package stats defines scoped product inventory and usage statistics.
transportpolicy Package transportpolicy defines the shared network transport trust rules used by PowerContext process and client surfaces.	Package transportpolicy defines the shared network transport trust rules used by PowerContext process and client surfaces.
webui Package webui embeds and serves the local PowerContext web interface.	Package webui embeds and serves the local PowerContext web interface.
work Package work models the human-agent work continuity loop.	Package work models the human-agent work continuity loop.
openapi Package openapi owns generation of the immutable HTTP contract.	Package openapi owns generation of the immutable HTTP contract.
server Package server provides the public PowerContext server configuration and lifecycle facade.	Package server provides the public PowerContext server configuration and lifecycle facade.
source Package source defines the public Source model, adapters, catalog, and standard evidence sources.	Package source defines the public Source model, adapters, catalog, and standard evidence sources.
tools
api-baseline command Command api-baseline writes path-independent Go export data for an approved subset of one module's public packages.	Command api-baseline writes path-independent Go export data for an approved subset of one module's public packages.
api-generate command Command api-generate generates the Go HTTP contract from the frozen OpenAPI document without modifying that authoritative file.	Command api-generate generates the Go HTTP contract from the frozen OpenAPI document without modifying that authoritative file.
fixture-generate command Command fixture-generate freezes deterministic metadata from the Python PowerContext oracle.	Command fixture-generate freezes deterministic metadata from the Python PowerContext oracle.
governance-check command
locomo command Command locomo runs the long-lived, credentialed LoCoMo evaluation outside the production PowerContext binary.	Command locomo runs the long-lived, credentialed LoCoMo evaluation outside the production PowerContext binary.
mcp-schema-generate command Command mcp-schema-generate derives the curated MCP tool schemas from the authoritative OpenAPI document.	Command mcp-schema-generate derives the curated MCP tool schemas from the authoritative OpenAPI document.
module-integrity command Command module-integrity verifies that every Go module owned by this repository has an explicit inventory entry and a committed checksum file.	Command module-integrity verifies that every Go module owned by this repository has an explicit inventory entry and a committed checksum file.
parity-inventory-generate command Command parity-inventory-generate builds the 812-case Python test inventory at the active parity target recorded in test/conformance/parity-contract.json.	Command parity-inventory-generate builds the 812-case Python test inventory at the active parity target recorded in test/conformance/parity-contract.json.
portable-sdk-check command Command portable-sdk-check rejects direct native, filesystem, environment, process-lifecycle, and SQL imports from the deliberate pure public SDK.	Command portable-sdk-check rejects direct native, filesystem, environment, process-lifecycle, and SQL imports from the deliberate pure public SDK.
process-smoke command Command process-smoke verifies a built PowerContext release through only its public process interfaces.	Command process-smoke verifies a built PowerContext release through only its public process interfaces.
race-debt command Command race-debt validates the bounded ledger for temporary race-test exclusions.	Command race-debt validates the bounded ledger for temporary race-test exclusions.
release command Command release builds auditable, deterministic PowerContext release bundles.	Command release builds auditable, deterministic PowerContext release bundles.
release-contract-verify command Command release-contract-verify compares the checked-in PowerContext release contract with the current official GitHub release and PyPI provenance records.	Command release-contract-verify compares the checked-in PowerContext release contract with the current official GitHub release and PyPI provenance records.
traceability-generate command Command traceability-generate expands the frozen Python test inventory into a case-by-case implementation evidence table.	Command traceability-generate expands the frozen Python test inventory into a case-by-case implementation evidence table.
trigger Package trigger defines sans-I/O policies and their immutable transitions.	Package trigger defines sans-I/O policies and their immutable transitions.