A Go library for typed LLM context: durable message identity, prompt/checkpoint projections, token budgets, resources, lineage and optimistic checkpoint storage. The host supplies its own metadata, tokenizer, policies and callbacks. Tool execution, model clients, retries and agent loops stay in the host.
This contract makes a clear break in explicit target composition, selection and export, budget configuration, compile-only selectors, deferred callback results and transformation status. See the consumer migration guide before updating stored state or callers; old checkpoint/OCC namespaces may need explicit host migration.
go get github.com/skosovsky/contextyRequires Go 1.27.1+.
make lint uses golangci-lint from PATH. CI pins golangci-lint 2.14.0 and Go 1.27.2.
go run ./examples/quickstartThe complete example handles every error, gives static messages explicit IDs and current events a durable TurnID, supplies an explicit estimator, and commits with the loaded OCC version. It prints separate prompt-safe and raw checkpoint content. The bundled memory backend and structural estimator are reference implementations; hosts choose durability and tokenization.
Compile does not commit state. Retry the same logical turn with the same TurnID; assign a new TurnID to a new event. Nil System/History/Memory inherits stored data; a nonnil empty slice clears that segment for this compile. Tools is request-only. Returned result DTOs are owned mutable copies; ConversationState is a private immutable view with defensive getters.
- API guide and examples: messages, tools, deferred blocks, views, targets and wire contracts.
- Glossary, migration, contracts.
- Budget and retention, checkpoint stores.
- Projections, output policy, opaque state.
- Resources, blob retention, prefix diagnostics.
- Release and recovery, ownership/concurrency matrix.
- Review decisions and measurements.
make lint
make test
make test-integration
make test-e2eUse golangci-lint 2.14.0 and Docker for isolated Redis/Postgres integration tests. All four modules are discovered automatically, with GOWORK=off. Missing mandatory prerequisites fail the selected profile. See verification for test tags, tooling and separate live/benchmark/fuzz commands.
The closed role contract supports system, developer, user, assistant and tool.
Unknown or empty roles return ErrInvalidRole at compile, projection and storage
boundaries. Use RoleDeveloper; instruction retention and trust remain explicit
host policy. The SupportedMapping and
optional offline consumer demonstrate native mapping,
opaque state, final request evidence and terminal history CAS without dependencies
in core.