Documentation
¶
Overview ¶
Package contextpack assembles everything needed to work on something into one bundle.
It sits above the retrieval systems rather than beside them. memory, index, graph, secretary, and session each already answer one question well; what was missing was the thing that decides *which* of them to ask for a given task, in what proportion, and how to spend a fixed token budget across the answers. That judgement does not belong in the MCP server — which should stay an adapter — nor in internal/project, which would have to import half the repo.
The distinction that matters: recall answers "what do you know about X", and this answers "give me what I need to do X". The second is not a longer version of the first. It includes where the last agent stopped, what they ruled out, what is still open, and the actual text of the notes involved — and it leaves things out on purpose, because the consumer has a finite context window.
Index ¶
Constants ¶
const DefaultBudget = 4000
DefaultBudget is roughly a page and a half of context — enough to be useful, small enough that a host can afford to call this on every task.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Line ¶
type Line struct {
Section string `json:"section"`
Tokens int `json:"tokens"`
Items int `json:"items"`
Dropped int `json:"dropped"`
}
A Line is one section's spend, including what it could not fit.
type Pack ¶
type Pack struct {
Task string `json:"task"`
Hint string `json:"hint"`
Project *project.Project `json:"project,omitempty"`
// Worktree is the linked worktree continuity was read from, if any, and
// Inherited says the checkpoint below came from the project rather than
// from this worktree — a distinction the render has to make out loud.
Worktree string `json:"worktree,omitempty"`
Inherited bool `json:"inherited,omitempty"`
// Checkpoint is where the last agent stopped on this project, and Working is
// what has been recorded since without being committed. Together they are the
// answer to "where were we", which no amount of semantic recall provides.
Checkpoint *session.Checkpoint `json:"checkpoint,omitempty"`
Working []session.Note `json:"working,omitempty"`
// History is earlier checkpoints on the same project. Only their ruled-out
// approaches are used — see Build.
History []session.Checkpoint `json:"history,omitempty"`
// Notes is vault content — the actual prose, not just titles. Hits reached
// through the graph rather than matched directly carry Via.
Notes []index.Hit `json:"notes"`
Preferences []memory.Memory `json:"preferences"`
Related []memory.Memory `json:"related"`
// Pinned holds memories the user marked always-include (see memory.Pin).
// They bypass ranking entirely — see spendMemories — which is the whole
// difference between a pin and simply having high salience.
Pinned []memory.Memory `json:"pinned,omitempty"`
OpenLoops []secretary.Commitment `json:"open_loops"`
// Superseded holds recalled memories a later statement replaced. They are
// kept out of the answer but reported, so the agent knows the value moved
// rather than seeing one figure and assuming it was always so.
Superseded []memory.Memory `json:"superseded,omitempty"`
// Conflicts names sources that disagree and cannot be ordered. Unlike
// supersession this resolves nothing — it says so out loud instead.
Conflicts []string `json:"conflicts,omitempty"`
// Window is the span of time the task asked about, when it asked about one,
// and OutOfWindow counts what was set aside for falling outside it. The
// count is rendered and the contents are not: an item excluded for being the
// wrong date does not become less wrong for being listed, and reprinting it
// would undo the filter. The number is there so the agent knows a filter ran
// and can ask again without one.
Window *when.Window `json:"window,omitempty"`
OutOfWindow int `json:"out_of_window,omitempty"`
// WindowEmpty is set when the window matched nothing dated, in which case the
// filter was abandoned rather than applied and the pack holds everything it
// gathered.
WindowEmpty bool `json:"window_empty,omitempty"`
// Sources lists what actually made it into the render, so the consumer can
// cite rather than paraphrase.
Sources []string `json:"sources"`
// Excluded names what the budget dropped. An agent that can see what it did
// not get can ask for more, which is strictly better than not knowing.
Excluded []string `json:"excluded"`
Budget Budget `json:"budget"`
}
A Pack is everything relevant to one task, gathered from every store, ready to be rendered into a model's context window.
func Build ¶
Build gathers candidates from every store. It deliberately over-gathers: what survives is decided at render time by the budget, because how much fits depends on how long each piece turns out to be.
Everything here degrades rather than fails. A vault with no project notes, no embedding model, or no checkpoints still produces a useful pack — a memory layer that errors because you asked about something it doesn't know is worse than useless, it is untrustworthy.
func (Pack) Carried ¶ added in v0.1.3
Carried is a one-line inventory of what this pack actually contains: the receipt a host shows the user so a restore is something they can see happen rather than something they have to take on faith.
It counts and never characterises. "4 memories" is checkable against the text below it; "the important context" is not, and the moment a receipt says something the body does not support, every later receipt is worth less.
Empty when the pack carries nothing, so a caller can tell "restored nothing" from "restored things I did not enumerate" and say the honest one.
func (Pack) Continuity ¶
Continuity is the scope this pack's sessions and checkpoints are filed under: the project, narrowed to the worktree when the agent is standing in a linked one. Exported because a caller that wants to write into the same session — a note saying it resumed, say — has to key it the way the pack read it.
A path segment rather than a joined name, because that is what it becomes in the vault: sessions/kestrel/feature-x/, a folder inside the project's rather than a sibling of it. A worktree is not another project — it is the same repository with a second working tree — and the layout should not claim otherwise. It also means a main checkout is untouched by any of this: its history is the files directly inside sessions/kestrel/, and a listing that skips directories cannot see the worktrees at all.
func (*Pack) Empty ¶ added in v0.2.0
Empty reports that retrieval found nothing at all — not "nothing that answers the task", which renderGaps already says, but nothing whatsoever.
The render is written for the agent that consumes it, and for an agent an empty pack is still a useful answer: it says do not infer, nothing is here. For a person running `brain resume` as their first command after setup, the same output is a page of scaffolding around a void, and it reads like a broken install rather than an empty vault. Callers use this to tell the two audiences apart.
type Request ¶
type Request struct {
Task string
// Hint narrows the scope: a project name, a file path, or a topic. Optional
// — if empty, the task text is matched against known projects.
Hint string
// Worktree is the linked git worktree the agent is standing in, empty in a
// main checkout. It narrows continuity and nothing else: a worktree is the
// same repository and so has the same memory, but its own uncommitted work
// and its own place to have stopped.
Worktree string
// Budget is the approximate token ceiling for the rendered pack. 0 means
// DefaultBudget.
Budget int
// Now is the clock the task's time expressions are resolved against. Zero
// means the wall clock. It exists so "what was I working on last month" is
// testable, and because a benchmark and a replay both need to ask the
// question as of a moment that is not this one.
Now int64
}
A Request is what the caller is trying to do. Task is the important field: "continue the MCP implementation" retrieves differently from the project name alone, because it says which corner of the project matters right now.
Source Files