Documentation
¶
Overview ¶
Package capture implements the agent-reasoning-capture buffer that the Stop hook appends to after every assistant turn. The buffer is a JSONL file per Claude Code session under .contexo/raw/sessions/_pending/, kept bounded by per-turn truncation and a hard turn cap.
The buffer is read by the ctx_push MCP tool's distill handshake (Phase 1) to produce a structured "source" page. See docs/specs/2026-05-17-agent- reasoning-capture-design.md.
Index ¶
Constants ¶
const ( PendingDirRel = "raw/sessions/_pending" ArchiveDirRel = "raw/sessions/_pending/_archive" MaxAssistantBytes = 4 * 1024 MaxUserBytes = 2 * 1024 MaxTurns = 500 DropOldestOnOverflow = 100 )
File-tree constants. All paths are relative to the .contexo directory.
Variables ¶
This section is empty.
Functions ¶
func PruneOlderThan ¶
PruneOlderThan deletes pending buffer files whose mtime is older than maxAge. Returns the count of removed files.
func TakePendingPrompt ¶ added in v0.5.0
TakePendingPrompt reads and removes the pending prompt for a session. Returns "" (no error) when there is none.
func WritePendingPrompt ¶ added in v0.5.0
WritePendingPrompt stores the latest user prompt for a session, overwriting any previous unpaired prompt.
Types ¶
type Buffer ¶
Buffer is one session's pending capture file.
func List ¶
List returns all non-archived buffers in the .contexo directory, sorted by modification time descending (most-recent first). Empty list if the pending directory does not exist.
func MostRecent ¶
MostRecent returns the most-recently-modified buffer whose mtime is within maxAge of now. Returns nil (no error) if none qualifies.
func Open ¶
Open returns a Buffer handle for the given session. Does not create the file; AppendTurn does that on first write.
func (*Buffer) AppendTurn ¶
func (b *Buffer) AppendTurn(rec TurnRecord) error
AppendTurn writes one record. Truncates oversized fields, dedupes by turn index against existing records, and inserts a marker line when the buffer would exceed MaxTurns. If rec.Turn is zero or negative, it is auto-assigned to one past the current last turn.
func (*Buffer) Archive ¶
Archive moves the buffer file from _pending/ to _pending/_archive/. No-op if the file does not exist.
func (*Buffer) Records ¶
func (b *Buffer) Records() ([]TurnRecord, error)
Records returns all turn records in append order. Returns nil if the buffer file does not exist.
type Exchange ¶
Exchange is one user→assistant exchange extracted from a Claude Code transcript file.
func LatestExchange ¶
LatestExchange returns the most recent (user, assistant, tools) tuple from the JSONL transcript at path. Returns an empty Exchange (no error) if the transcript has no assistant turns yet.
type TruncationTag ¶
TruncationTag marks a marker line inserted when older turns are dropped to keep the buffer under MaxTurns.
type TurnRecord ¶
type TurnRecord struct {
Timestamp string `json:"ts,omitempty"`
Turn int `json:"turn"`
User string `json:"user,omitempty"`
Assistant string `json:"assistant,omitempty"`
Tools []string `json:"tools,omitempty"`
Truncated *TruncationTag `json:"truncated,omitempty"`
}
TurnRecord is one JSONL line in the buffer.
Source Files