Documentation
¶
Overview ¶
Package contextmgr implements the Tokenizer, Budgeter, and Checkpointer ports (ADR-0008): estimate token cost, decide what enters the context window in priority order, and checkpoint/reconstruct when the window fills up.
Token counts are deliberately approximate. ADR-0008 treats the budget as a soft ceiling with a safety margin, so a calibrated per-family heuristic is the default. An exact counter (tiktoken BPE, or a provider count endpoint) can be dropped in behind the Tokenizer port without touching callers — the heuristic ships first because a BPE table fetched over the network at runtime would break the local-first guarantee.
Index ¶
Constants ¶
const ( AnthropicCharsPerToken = 3.6 OpenAICharsPerToken = 4.0 )
Characters-per-token ratios, calibrated against representative English prose and source code for each family. Anthropic's tokenizer runs slightly denser than the OpenAI cl100k/o200k families on the same text.
const DefaultHighWater = 0.8
DefaultHighWater is the fraction of the context window at which a checkpoint is taken when Checkpointer.HighWater is unset. Leaves headroom for the turn that writes the checkpoint itself.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Budgeter ¶
type Budgeter struct {
Tokenizer Tokenizer
// Budget is the soft token ceiling for the assembled context.
Budget int
}
Budgeter decides what enters the context window for a turn (ADR-0008). A zero Budget means no limit is configured and everything passes through.
func (Budgeter) Fit ¶
Fit assembles in into a budgeted Output, admitting sections in ADR-0008 priority order: system → active task + progress → reconstructed checkpoint → retrieved memory → retained recent messages. The system prompt is always kept, even if it alone exceeds the budget: a context without it is useless, and ADR-0008 treats the budget as a soft ceiling.
type Checkpoint ¶
type Checkpoint struct {
// Summary is the condensed narrative of what happened before the cut.
Summary string
// Tasks is the task tree, which must survive the boundary intact (T-063).
Tasks TaskTree
// Recent holds the messages retained verbatim across the cut.
Recent []ports.Message
}
Checkpoint is a structured snapshot of a session's working state.
type Checkpointer ¶
type Checkpointer struct {
// Root is the directory holding checkpoint.md.
Root string
// Window is the model's context window in tokens. Zero means unknown, in
// which case checkpointing never triggers automatically.
Window int
// HighWater is the fraction of Window that triggers a checkpoint. Zero uses
// DefaultHighWater.
HighWater float64
}
Checkpointer writes and reads checkpoint.md and decides when the live context has grown enough to warrant a cut (ADR-0008).
func (Checkpointer) Read ¶
func (c Checkpointer) Read() (Checkpoint, error)
Read loads the checkpoint. A missing file yields a zero Checkpoint and no error — the first session has nothing to reconstruct.
func (Checkpointer) Reconstruct ¶
func (c Checkpointer) Reconstruct(system string, memory []string, recent []ports.Message) (Input, error)
Reconstruct reads the checkpoint and assembles a Budgeter Input in ADR-0008 injection order: the caller's system prompt, the checkpoint's active task, the checkpoint summary, retrieved memory, and retained recent messages. recent overrides the checkpoint's digest when non-nil (live messages are better than a digest of them).
func (Checkpointer) ShouldCheckpoint ¶
func (c Checkpointer) ShouldCheckpoint(used int) bool
ShouldCheckpoint reports whether used tokens have reached the high-water mark.
func (Checkpointer) Write ¶
func (c Checkpointer) Write(cp Checkpoint) error
Write persists cp to <Root>/checkpoint.md, replacing any previous checkpoint.
type Heuristic ¶
type Heuristic struct {
CharsPerToken float64
}
Heuristic is a characters-per-token estimator. A zero CharsPerToken falls back to the OpenAI ratio.
type Input ¶
type Input struct {
// System is the system prompt. Never dropped — without it the agent loses
// its identity and rules.
System string
// Task is the active task description (highest-priority working state).
Task string
// Progress is the active task's progress notes.
Progress string
// Checkpoint is the reconstructed checkpoint summary.
Checkpoint string
// Memory holds hybrid-retrieved memory chunks, most relevant first
// (ADR-0003).
Memory []string
// Recent holds retained recent messages in chronological order.
Recent []ports.Message
}
Input is everything that could enter the context window for one turn, before budgeting. Sections are listed in ADR-0008 priority order.
type Output ¶
type Output struct {
System string
Task string
Progress string
Checkpoint string
Memory []string
Recent []ports.Message
// Used is the estimated token count of the retained content.
Used int
// Dropped counts the sections and items that did not fit.
Dropped int
}
Output is the budgeted context: the same sections, truncated to fit.
type TaskNode ¶
TaskNode is one task in the tree. Nesting is encoded in the dotted ID ("T1" is a root, "T1.1" is its child) so the tree is flat in memory but renders and reparses as a hierarchy (T-063).
type TaskTree ¶
type TaskTree struct {
Nodes []TaskNode
}
TaskTree is the ordered task list that survives checkpoint boundaries.
func ParseTaskTree ¶
ParseTaskTree restores a tree from Render's output. Lines that do not match the task shape are ignored, so the tree can be embedded in a larger document.
func (TaskTree) Active ¶
Active returns the first in-progress task — the one the Budgeter treats as highest-priority working state (ADR-0008).
type Tiktoken ¶
type Tiktoken struct {
// contains filtered or unexported fields
}
Tiktoken is the exact token counter backed by github.com/pkoukk/tiktoken-go (Change 0005 / T-452). It satisfies the Tokenizer port for OpenAI-shaped model prefixes. Anthropic stays on the heuristic — Anthropic's BPE isn't publicly published.
func NewTiktoken ¶
NewTiktoken builds a Tiktoken for the given "<provider>/<model>" string. It picks cl100k_base for gpt-4/gpt-3.5-turbo-style models and o200k_base for gpt-4o/gpt-4.1/gpt-4.5 family, falling back to cl100k_base when the model is unrecognized. Returns an error when the underlying tiktoken-go call fails (e.g. network blip on first download) — callers should fall back to Heuristic rather than failing the whole turn.