Documentation
¶
Overview ¶
Package store is the single-file SQLite core store for personal sessions: sessions, a linear entry log, turns (agentcore run state) and events.
Index ¶
- Constants
- Variables
- func CheckIntegrity(ctx context.Context, db *sql.DB) error
- func DatabaseFileBytes(path string) int64
- func EncodeMessage(m api.Message) ([]byte, error)
- func FreeDiskSpace(path string) (uint64, error)
- func HandoffReuseKey(value string) string
- func ImageExtension(mediaType string) string
- func ImageRef(sha, mediaType string) string
- func InteractiveSession(sess Session) bool
- func IsAgentSession(sess Session) bool
- func IsDuplicateKey(err error) bool
- func MediaTypeForRef(ref string) string
- func ParentSession(sess Session) string
- func Percentile(vals []int64, p float64) int64
- func PinnedSession(sess Session) bool
- func RestoreMessageJSON(raw []byte) []byte
- func SessionImagesDir(sessionsDir, sessionID string) string
- func SessionOrigin(sess Session) string
- func SessionUsedInteractively(sess Session) bool
- func StoreImage(imagesDir string, data []byte, mediaType string) (api.ImagePart, error)
- type AgentStorage
- func (a *AgentStorage) AppendMessages(ctx context.Context, runID string, msgs ...api.Message) error
- func (a *AgentStorage) LoadMessages(ctx context.Context, runID string) ([]api.Message, error)
- func (a *AgentStorage) LoadRun(ctx context.Context, runID string) (*api.RunState, error)
- func (a *AgentStorage) SaveRun(ctx context.Context, state *api.RunState) error
- func (a *AgentStorage) WithSessionsDir(dir string) *AgentStorage
- type BodyRef
- type CacheBucketStat
- type CacheBuckets
- type CacheCall
- type CacheLowHit
- type Entry
- type EntryFilter
- type EntryHit
- type EntryRef
- type EntrySearch
- type Event
- type EventFilter
- type ExcludeSession
- type ForkInput
- type GCReport
- type GCRetentionClassReport
- type GCRetentionPolicy
- type GCRetentionReport
- type MemoryHit
- type MemoryMeta
- type MemoryRef
- type MemorySource
- type ModelStat
- type NamedStat
- type NewEntry
- type Option
- type Report
- type RewindRecord
- type SearchResult
- type SeqRange
- type SeqRanges
- type Session
- type SizeStat
- type Store
- func (s *Store) AgentStorage() *AgentStorage
- func (s *Store) AppendEntries(ctx context.Context, sessionID string, in ...NewEntry) ([]Entry, error)
- func (s *Store) AppendEvent(ctx context.Context, e Event) (Event, error)
- func (s *Store) BackfillMemoryUUIDs(ctx context.Context) error
- func (s *Store) BuildCacheBuckets(ctx context.Context, f EventFilter, lowHitLimit int) (CacheBuckets, error)
- func (s *Store) BuildReport(ctx context.Context, f EventFilter) (Report, error)
- func (s *Store) Close() error
- func (s *Store) CollectGarbage(ctx context.Context, cutoff time.Time, keep map[string]bool, apply bool) (GCReport, error)
- func (s *Store) CollectGarbageByRetention(ctx context.Context, now time.Time, policy GCRetentionPolicy, ...) (GCRetentionReport, error)
- func (s *Store) CountEntriesByType(ctx context.Context, sessionID, typ string) (int, error)
- func (s *Store) CountEntriesByTypeSkipping(ctx context.Context, sessionID, typ string, skip SeqRanges) (int, error)
- func (s *Store) CountTurns(ctx context.Context, sessionID string) (int, error)
- func (s *Store) CountTurnsSkipping(ctx context.Context, sessionID string, skip SeqRanges) (int, error)
- func (s *Store) CreateForkedSession(ctx context.Context, in ForkInput) error
- func (s *Store) CreateSession(ctx context.Context, in Session) error
- func (s *Store) CreateTurn(ctx context.Context, in Turn) error
- func (s *Store) DB() *sql.DB
- func (s *Store) DeleteSession(ctx context.Context, id string) error
- func (s *Store) DeleteSessionFiles(sessionIDs ...string) error
- func (s *Store) EnsureMemoryUUID(ctx context.Context, backend string, sc memory.Scope, id string) (string, error)
- func (s *Store) EntriesAround(ctx context.Context, sessionID string, seq int64, window int) ([]Entry, error)
- func (s *Store) EntriesFromSkipping(ctx context.Context, sessionID string, types []string, fromSeq int64, ...) ([]Entry, error)
- func (s *Store) FTSShrinkPending(ctx context.Context) (bool, error)
- func (s *Store) GetSession(ctx context.Context, id string) (Session, error)
- func (s *Store) GetTurn(ctx context.Context, id string) (Turn, error)
- func (s *Store) HasSearchableEntries(ctx context.Context, q EntrySearch) (bool, error)
- func (s *Store) HydrateEntries(ctx context.Context, sessionID string, entries []Entry) error
- func (s *Store) IsTombstoned(ctx context.Context, backend string, sc memory.Scope, fingerprint string) (bool, error)
- func (s *Store) LastEntryAt(ctx context.Context, sessionID string) (time.Time, error)
- func (s *Store) LastEntrySeq(ctx context.Context, sessionID string) (int64, error)
- func (s *Store) LatestEntry(ctx context.Context, sessionID, typ string) (*Entry, error)
- func (s *Store) LatestEntrySkipping(ctx context.Context, sessionID, typ string, skip SeqRanges) (*Entry, error)
- func (s *Store) ListEntries(ctx context.Context, sessionID string, f EntryFilter) ([]Entry, error)
- func (s *Store) ListEntryRefs(ctx context.Context, sessionID string) ([]EntryRef, error)
- func (s *Store) ListEvents(ctx context.Context, f EventFilter) ([]Event, error)
- func (s *Store) ListSessions(ctx context.Context) ([]Session, error)
- func (s *Store) ListTurns(ctx context.Context, sessionID string, statuses ...string) ([]Turn, error)
- func (s *Store) MemoryMetaRows(ctx context.Context, backend string, sc memory.Scope) ([]MemoryMeta, error)
- func (s *Store) MemoryRefByUUID(ctx context.Context, uuid string) (MemoryRef, error)
- func (s *Store) MoveAssistantBodies(ctx context.Context, opts ToolBodyMaintOptions) (ToolBodyMaintReport, error)
- func (s *Store) MoveToolBodies(ctx context.Context, opts ToolBodyMaintOptions) (ToolBodyMaintReport, error)
- func (s *Store) PatchSessionMeta(ctx context.Context, id string, patch map[string]any) error
- func (s *Store) PatchSessionMetaIfAbsent(ctx context.Context, id, guard string, patch map[string]any) (bool, error)
- func (s *Store) Path() string
- func (s *Store) RecentEntries(ctx context.Context, sessionID string, types []string, limit int) ([]Entry, error)
- func (s *Store) RecentEntriesSkipping(ctx context.Context, sessionID string, types []string, skip SeqRanges, ...) ([]Entry, error)
- func (s *Store) Record(ctx context.Context, backend string, sc memory.Scope, e memory.Entry, ...) error
- func (s *Store) RemoveToolBodyFiles(ctx context.Context) (removed int, err error)
- func (s *Store) ResetToolBodyState(ctx context.Context) error
- func (s *Store) RewindRecords(ctx context.Context, sid string) ([]RewindRecord, error)
- func (s *Store) SearchEntries(ctx context.Context, q EntrySearch) ([]EntryHit, error)
- func (s *Store) SearchEntriesPage(ctx context.Context, q EntrySearch) (SearchResult, error)
- func (s *Store) SearchMemoryIndex(ctx context.Context, scope, q string, limit int) ([]MemoryHit, error)
- func (s *Store) SessionCwds(ctx context.Context) (map[string]string, error)
- func (s *Store) SetToolBodyMove(ctx context.Context, enabled bool) error
- func (s *Store) Snapshot(ctx context.Context, destination string) error
- func (s *Store) SumUsage(ctx context.Context, sessionID string) (Usage, error)
- func (s *Store) SumUsageTree(ctx context.Context, sessionID string) (Usage, error)
- func (s *Store) SyncMemoryIndex(ctx context.Context, scope string, sources []MemorySource) (added, removed int, err error)
- func (s *Store) Tombstone(ctx context.Context, backend string, sc memory.Scope, id, fingerprint string) error
- func (s *Store) ToolBodyCheck(ctx context.Context) (ToolBodyCheckReport, error)
- func (s *Store) ToolBodyStatus(ctx context.Context) (ToolBodyStatus, error)
- func (s *Store) UndoToolBodies(ctx context.Context, opts ToolBodyMaintOptions) (ToolBodyMaintReport, error)
- func (s *Store) UpdateEventEntrySeq(ctx context.Context, id, seq int64) error
- func (s *Store) UpdateSession(ctx context.Context, in Session) error
- func (s *Store) UpdateSessionFields(ctx context.Context, in Session) error
- func (s *Store) UpdateTurn(ctx context.Context, t Turn) error
- func (s *Store) UpsertTurnState(ctx context.Context, turnID string, stateJSON []byte) error
- func (s *Store) Usage(ctx context.Context, opts UsageOptions) (UsageReport, error)
- func (s *Store) Vacuum(ctx context.Context) (VacuumResult, error)
- type ToolBodyCheckReport
- type ToolBodyMaintOptions
- type ToolBodyMaintProgress
- type ToolBodyMaintReport
- type ToolBodyStatus
- type ToolStat
- type Turn
- type Usage
- type UsageAssistant
- type UsageEntries
- type UsageEvents
- type UsageFTS
- type UsageFile
- type UsageOptions
- type UsageReport
- type UsageSession
- type UsageSessions
- type UsageTable
- type UsageToolEntries
- type VacuumResult
Constants ¶
const ( // BucketCold is the session's first call: the provider has nothing cached // for it. BucketCold = "cold" // BucketSegmentStart is the first call after a segment break: compaction // wrote a handoff package and the request starts from the new segment. BucketSegmentStart = "segment_start" // BucketAfterFold is the first call after old tool results were folded or // the prefix changed some other way (a truncation, a loaded deferred tool, a // changed system prompt, a rewritten message). BucketAfterFold = "after_fold" // BucketSteady is a call whose request only extends the previous one inside // a running segment: the bucket the 95% target is about. BucketSteady = "steady" // BucketHandoff is a side call that writes a handoff package // (attrs.purpose=compact): it sends its own prompt, not the conversation. BucketHandoff = "handoff" // BucketResume is the first call of a new process that resumed the session // inside the same segment (prefix=first, no segment break in between) without // a persisted request fingerprint (a session recorded before it existed): // `suga run --resume` from gofer and the per-turn processes of the eval land // here when nothing was persisted to compare with. BucketResume = "resume" // BucketResumeSame is that first call when the persisted fingerprint of the // previous process is a prefix of it: the request was only appended to, so a // provider cache that still holds the session serves it like a steady call. BucketResumeSame = "resume_same" // BucketResumeChanged is that first call when the persisted fingerprint // differs (system prompt, tool table or an earlier message): the prefix has // to be sent again however warm the cache is. BucketResumeChanged = "resume_changed" // BucketProviderSwitch is a call the previous main-loop call's cache cannot // serve because another model or provider answered it: the model attr changed, // the pool fell back to the next provider, or a model_switch session event lies // in between. The request bytes only grow (fold/rewrite would be needed to // change them), so without this bucket such a call reads as steady. BucketProviderSwitch = "provider_switch" // BucketUnknown is a call the trace cannot classify; today only kept for a // prefix reason this code does not know. BucketUnknown = "unknown" )
Cache buckets: one class per model call, decided by what happened to the request prefix since the session's previous main-loop call. A provider prompt cache serves the prefix it already saw, so a call that only extends the conversation reuses most of the prompt (steady) while a prefix break has to be sent again (the handoff package of a new segment, old tool results folded, a loaded deferred tool, a changed system prompt). The steady bucket is the one the 95% hit target is about; see docs/research for the definition and the measured numbers.
const ( // MetaOrigin is the session meta key holding the entry point. MetaOrigin = "origin" // OriginChat is an interactive `suga chat`, OriginRun a one-shot // `suga run`, OriginACP a session an editor created over ACP, // OriginAgent a sub-agent session and OriginSDK an embedded SDK session. OriginChat = "chat" OriginRun = "run" OriginACP = "acp" OriginAgent = "agent" OriginSDK = "sdk" // MetaPinned marks a session that an embedding host still references. GC // treats a JSON boolean true as a keep-forever marker until it is cleared. MetaPinned = "pinned" // MetaUsedInteractively marks a session created by a non-interactive entry // point that a chat continued afterwards: from then on it counts as // interactive. MetaUsedInteractively = "used_interactively" )
Session origins (meta.origin). A session records which entry point created it, and `suga data gc --retention` picks the retention period from that: an interactive chat is worth keeping much longer than a session a batch job or an editor integration started (design 0.3, 会话来源).
const ( MetaKind = "kind" KindAgent = "agent" MetaParentSession = "parent_session_id" )
Sub-agent sessions: a session a sub-agent ran in carries meta kind "agent" and the id of the session that started it. They are kept out of session lists and searches (they belong to their parent), counted in the parent's cumulative usage (SumUsageTree) and removed with the parent (gc).
const ( // DefaultToolBodyInlineBytes is store.body_inline_bytes: entry JSON // above this many bytes moves to the session file. 0 keeps everything inline. DefaultToolBodyInlineBytes int64 = 1024 // BodyFileName is the current append-only file of one session's moved bodies. BodyFileName = "bodies.jsonl" // LegacyBodyFileName is the v0.36 file name. A ledger v0.40 never renamed still // writes it, so a suga of the previous version running next to this one keeps // reading its own files; the reader tries both names. (v0.38 dropped the // ToolBodyFileName alias of it.) LegacyBodyFileName = "tools.jsonl" )
const ( SessionOpen = "open" SessionRunning = "running" SessionArchived = "archived" )
Session lifecycle states stored in sessions.status.
const ( TurnRunning = "running" TurnCompleted = "completed" TurnFailed = "failed" TurnCancelled = "cancelled" )
Turn lifecycle states stored in turns.status.
const ( EntryUser = "user" EntryAssistant = "assistant" EntryTool = "tool" EntryCompaction = "compaction" EntryPlan = "plan" EntryHandoff = "handoff" EntryContextUpdate = "context_update" // EntryAdmit is the ledger row of one tool call with side effects, written // before the call runs (issue suga-r72b): an interrupted turn finds an // admitted call without a tool result and answers it as "state unknown" // instead of replaying it. It is never a model message. EntryAdmit = "admit" // EntryRewind marks a conversation rewind (session rewind design 0.2): its // JSON is {cut_seq, target_turn, scope, files}. The entries with a seq inside // (cut_seq, this record's seq) are masked for the readers that build model // context; nothing is deleted and no seq is reused. EntryRewind = "rewind" )
Entry types stored in entries.type. A context_update records what changed inside a segment (rules, append prompt, environment, a missing memory index); it belongs to a turn, is adopted with it and is replayed as a user message at its seq until the next segment record supersedes it.
const ( EventModel = "model" EventTool = "tool" EventDenial = "denial" EventTurn = "turn" EventCompaction = "compaction" EventToolSearch = "tool_search" // EventTurnContext records what a turn starts with (model, mode, tool // set, rules/memory snapshot hashes, taint); see D9. EventTurnContext = "turn_context" // EventSchedule records a host scheduler event (chat idle consolidation: // name = task name, status and attrs.event = what happened). EventSchedule = "schedule" // EventFold records a history folding boundary move: attrs boundary, // steps, chars_before and chars_after of the request view. EventFold = "fold" // EventContext records what the first model request of a turn is made // of: chars per part (system prompt, tools, segment context parts, // history, hook context, the turn's input) and the window. EventContext = "context" // EventContextCleared records a --clear-ctx segment break: the session // started its next turn on an empty segment (attrs dropped_messages, // est_tokens, first_kept_seq, segment). The old entries stay in the log and // stay searchable; only the next turn's context stops at the new record. EventContextCleared = "context_cleared" // EventHook records a run of the user's hook command: name = hook event, // attrs decision, additional_chars, notice. EventHook = "hook" // EventTask records the end of a background task: name = task id, attrs // arg (the command), exit_code, bytes, lines, ref, truncated; started_at // and duration cover the task's whole run. EventTask = "task" // EventSession records a change of the session's own lifecycle, outside any // turn: name "recovered" is a session left running by a process that died // mid-turn taken back to open (attrs previous_status, stale_ms, turn_status), // name "session_cwd_changed" a session continued in another working directory // than the one it was created in (attrs from, to). EventSession = "session" // EventSteer records one message a person typed into a running turn // (steering): name "delivered" is a steer a model request carried (attrs // steer_id, source, chars, step), "returned" one the turn handed back // (attrs steer_id, source, chars, reason, disposition), "withdrawn" one the // person took back before a request carried it (attrs steer_id, source, // chars, count). EventSteer = "steer" // EventAddDir records a change of the session's added directories // (--add-dir) outside any turn: name "add" or "remove", attrs path, mode // (ro/rw) and from (keyboard: typed in chat; ask: authorized at an // outside-directory question). It is how a trace shows who widened the // session's reach and when; chat's :add-dir/:rm-dir and the authorization // write it. EventAddDir = "add_dir" // EventLocalCommand records one local command a person typed at the chat // prompt ("!cmd"/"!!cmd") outside any turn: name "run", attrs command (the // command, redacted), exit_code, bytes (the output the command wrote), // sent (true: the result goes to the model with the next message), // cancelled and timeout. It is how a trace shows what was run outside the // model's turn; chat writes it. EventLocalCommand = "local_command" // EventBudget records a budget threshold or accounting warning. Its attrs // carry scope, limits, usage, remaining amounts and the reason. EventBudget = "budget" // EventUndo records a user rollback; its attrs include the file outcome // counts and the seq of the deferred suga.undo entry when available. EventUndo = "undo" // EventVerify records one run of the --verify delivery check (suga run // --verify): name "run", attrs round (0 = the first check), exit, duration_ms, // output_len (everything the command wrote) and passed. EventVerify = "verify" // EventNudge records a hit of the "stopped too early" rules // (personal.CheckNudge): name "turn", attrs rule (N1/N2), action (pushed: an // injected turn follows; hinted: chat only showed a line; recorded: ACP only // wrote the trace) and evidence (what the rule found). EventNudge = "nudge" // EventOutputSchema records one check of the output contract (suga run // --output-schema): name "check", attrs round (1 = the first answer, 2 = the // correction round), action (ok/corrected/failed), passed, source // (whole/fenced/substring/no_json), errors (at most 5 "path: message") and the // schema's hash and size - never the schema itself. EventOutputSchema = "output_schema" // EventLoopGuard records one reminder the loop guard appended to a repeated // tool call's result: name = tool, attrs rule (R1 consecutive / R2 total // repeats within a turn) and count (which call of the group it was). EventLoopGuard = "loop_guard" // EventToolInterrupted records a tool call with side effects that a turn // ended before storing its result: name = tool, status "interrupted", // attrs invocation_id and call_id. The next turn's replay answers the call // as "state unknown" instead of running it again. EventToolInterrupted = "tool_interrupted" )
Event kinds stored in events.kind.
const FTSShrinkPendingNotice = "" /* 129-byte string literal not displayed */
FTSShrinkPendingNotice is the note a search result carries while the ledger still holds tool rows in the index: a search also matches tool output that the new index no longer covers, so "not found" would be read too strongly.
const GCDefaultOrphanEventRetention = 30 * 24 * time.Hour
GCDefaultOrphanEventRetention is how long the events of a session that no longer exists are kept before `gc --retention --apply` drops them.
const ImageDirName = "images"
ImageDirName is the directory of a session's images; api.ImagePart.Ref is a slash-separated path below it, relative to the session directory (images/<sha256>.<ext>).
const ResultSameAsContentKey = "ResultSameAsContent"
ResultSameAsContentKey is the top-level key that marks a stored tool message whose ToolResult.Content was omitted because it equals Content. api.Message reads it on decode (see its UnmarshalJSON).
const SteadyLowHitBelow = 0.90
SteadyLowHitBelow is the per-call hit rate under which a steady call is listed as a low hit (the target inside one context is higher, see BucketSteady).
Variables ¶
var ( // ErrSessionNotFound is returned when a session id does not exist. ErrSessionNotFound = errors.New("session not found") // ErrTurnNotFound is returned when a turn id does not exist. ErrTurnNotFound = errors.New("turn not found") )
var ErrToolBodyMissing = errors.New("tool body missing")
ErrToolBodyMissing is returned when a stub's body cannot be read back: the file is gone, the record is shorter than the stub says, or its seq/sha256 does not match. The reader never falls back to the stub's preview (D4).
Functions ¶
func CheckIntegrity ¶
CheckIntegrity verifies a staged SQLite database before it can replace the user's live store.
func DatabaseFileBytes ¶
DatabaseFileBytes is the size of the database file path plus its -wal and -shm side files, the number that matters for the free-space check: a VACUUM writes a new file of about the main size while the old one still exists.
func EncodeMessage ¶
EncodeMessage encodes a message for an entries row. A tool message whose ToolResult repeats its Content is stored once, with the ResultSameAsContent marker; every other message is encoded exactly as json.Marshal encodes it, so the stored bytes of everything else (and of the provider replay) are untouched.
func FreeDiskSpace ¶
FreeDiskSpace returns the bytes a caller may still write on the volume that path lives on (the free space available to this user, which is what a temporary VACUUM file of the same size needs).
func HandoffReuseKey ¶ added in v0.51.0
HandoffReuseKey is the aggregation key of a handoff_reuse value: the value itself, or its reason when it carries a detail suffix (fallback:prefix_changed :msg:12 names where the rebuilt request differs, which the aggregate counts with the plain reason).
func ImageExtension ¶
ImageExtension returns the stored-file extension of a media type (".bin" for an unknown one, which the image tools never produce).
func InteractiveSession ¶
InteractiveSession reports whether the retention rules count a session as interactive: created by a chat, continued by a chat, or created before meta.origin existed. A historical session is deliberately treated as interactive, that is as the class with the longer period.
func IsAgentSession ¶
IsAgentSession reports whether a sub-agent ran in the session.
func IsDuplicateKey ¶
IsDuplicateKey reports whether err is a primary-key or unique constraint violation, i.e. the id of the inserted row is already taken. A caller that generated the id can retry the insert with a fresh one; every other error is returned as is.
func MediaTypeForRef ¶
MediaTypeForRef returns the media type of a stored image by its file extension ("" when the extension is not one of the stored formats).
func ParentSession ¶
ParentSession is the session that started a sub-agent session ("" for others).
func Percentile ¶
Percentile returns the p-th percentile (0<p<=100) of vals by the nearest-rank method: the value at 1-based rank ceil(p/100*n) of the sorted data. Empty input yields 0. vals is not modified.
func PinnedSession ¶ added in v0.52.0
PinnedSession reports whether an embedding host has kept a durable reference to the session. It is deliberately independent of the session origin.
func RestoreMessageJSON ¶
RestoreMessageJSON returns a stored entry's JSON in the shape it had before the tool-result dedupe: an entry carrying the ResultSameAsContent marker is decoded (which restores ToolResult.Content) and encoded again the plain way; any other entry is returned as it is. Readers that hand stored JSON to the outside, such as `suga inspect export`, use it so the dedupe stays a storage detail.
func SessionImagesDir ¶
SessionImagesDir is the images directory of one session.
func SessionOrigin ¶
SessionOrigin returns the meta.origin of a session. It is empty for a session created before the key existed (by an older suga).
func SessionUsedInteractively ¶
SessionUsedInteractively reports whether a chat continued a session that a non-interactive entry point created (meta.used_interactively).
func StoreImage ¶
StoreImage writes one picture into imagesDir (a session's images directory) under its content-addressed name and returns the part that names it (Ref, SHA256, MediaType) without any bytes. It is the same atomic write AppendMessages does, exposed for a sender that fills the directory of another session (`suga send --image`): a file of the same sha256 is not written again.
Types ¶
type AgentStorage ¶
type AgentStorage struct {
// contains filtered or unexported fields
}
AgentStorage implements api.Storage on top of the core store with run_id == turn_id: SaveRun/LoadRun use turns.state_json, and messages are session entries tagged with the turn id.
The turn row must exist before SaveRun/AppendMessages (the Runner creates it first); a run id without a turn is reported as ErrTurnNotFound.
func (*AgentStorage) AppendMessages ¶
AppendMessages writes the batch as user/assistant/tool entries of the turn's session in one transaction.
func (*AgentStorage) LoadMessages ¶
LoadMessages returns the turn's messages in seq order. An unknown turn is a storage miss; a known turn with no messages yet returns an empty slice.
func (*AgentStorage) LoadRun ¶
LoadRun returns the saved snapshot. A missing turn or a turn without a saved snapshot is a storage miss (os.ErrNotExist), which agentcore treats as "start a fresh run" (see isStorageMiss in runtime.go).
func (*AgentStorage) SaveRun ¶
SaveRun upserts the RunState snapshot into the turn's state_json, without Messages: they are already the turn's session entries (AppendMessages), and a resumed run rebuilds them from there (agentcore.LoadRunAuthority replaces state.Messages with LoadMessages). Storing them twice doubled the database. Old rows that still carry Messages load unchanged.
func (*AgentStorage) WithSessionsDir ¶
func (a *AgentStorage) WithSessionsDir(dir string) *AgentStorage
WithSessionsDir makes AppendMessages write image files below <dir>/<session_id>/images. Without it images are stored with their reference only (the bytes are memory-only anyway, so they are not recoverable).
type BodyRef ¶
BodyRef is where one moved body lives: the raw entry JSON at Off, Len bytes long, with SHA256 over those bytes.
type CacheBucketStat ¶
type CacheBucketStat struct {
Bucket string `json:"bucket"`
Calls int `json:"calls"`
InputTokens int64 `json:"input_tokens"`
CacheRead int64 `json:"cache_read_tokens"`
CacheWrite int64 `json:"cache_write_tokens"`
CacheHitRate float64 `json:"cache_hit_rate"`
// CacheReported is false when no call of the bucket reported cache
// read/write: a provider without cache then shows "-" instead of 0%.
CacheReported bool `json:"cache_reported"`
// PrefixTokens is the summed estimated cacheable prefix of the calls' previous
// requests (tokens) and PrefixReuseRate = cache read / that: of what the
// provider could have served from its cache, how much it did serve. Unlike the
// hit rate it does not depend on how much a call added, so the steady 95%
// target is measured with it (docs/research/2026-10-26-cache-hit-buckets.md).
// A provider serving more than the estimate is counted as 100%, not more.
PrefixTokens int64 `json:"prefix_reused_tokens"`
PrefixReuse float64 `json:"prefix_reuse_rate"`
// Reasons counts the calls of a prefix-change bucket by cause (system, tools,
// fold, segment, rewrite): what to fix first.
Reasons map[string]int `json:"reasons,omitempty"`
// HandoffReuse counts the handoff-package calls of segment breaks by how they
// were made (prefix, fallback:<reason>): whether the reuse of the segment
// prefix held up (design 2026-10-27).
HandoffReuse map[string]int `json:"handoff_reuse,omitempty"`
}
CacheBucketStat aggregates the calls of one cache bucket. InputTokens follows the report convention (cache excluded), so prompt = input + cache read + cache write; CacheHitRate = cache read / prompt.
type CacheBuckets ¶
type CacheBuckets struct {
Buckets []CacheBucketStat `json:"cache_buckets"`
LowSteady []CacheLowHit `json:"steady_low_hit,omitempty"`
FailedAttempts int `json:"failed_attempts,omitempty"`
}
CacheBuckets is the cache classification of one session or of several runs.
func AggregateCacheBuckets ¶
func AggregateCacheBuckets(calls []CacheCall, lowHitLimit int) CacheBuckets
AggregateCacheBuckets pools classified calls into the per-bucket numbers plus the first lowHitLimit steady calls below SteadyLowHitBelow (0 lists none).
type CacheCall ¶
type CacheCall struct {
Bucket string `json:"bucket"`
// FailedAttempt marks a provider attempt with no usable token usage. It is
// retained for the aggregate's failed_attempts counter, never a bucket row.
FailedAttempt bool `json:"-"`
// Step is the 1-based ordinal of the main-loop model calls (the same step
// number the trace analysis uses); a handoff side call keeps the step of the
// call before it, since it is not a step of the loop.
Step int `json:"step"`
// Input includes the cache read/write of the call (the store's raw
// convention); the bucket statistics report it without them.
Input int64 `json:"input_tokens"`
CacheRead int64 `json:"cache_read_tokens"`
CacheWrite int64 `json:"cache_write_tokens"`
// After names the prefix-changing events (fold, segment, truncate, tools)
// recorded between the previous main-loop call and this one.
After []string `json:"after,omitempty"`
// Reason names why the call is in its bucket when the bucket is about a prefix
// change: the request-prefix reason (system / tools / fold / segment / rewrite),
// from attrs.prefix_resume_reason for a changed resume.
Reason string `json:"reason,omitempty"`
// PrefixTokens is the estimated size of the cacheable prefix of the previous
// request, in tokens: what a provider cache could have served of this call.
PrefixTokens int64 `json:"prefix_reused_tokens,omitempty"`
// HandoffReuse is how a handoff-package call of a segment break was made
// (attrs.handoff_reuse): prefix when it continued the segment's main-loop
// request, fallback:<reason> when the old path asked instead.
HandoffReuse string `json:"handoff_reuse,omitempty"`
}
CacheCall is one classified model call.
func ClassifyEvents ¶
ClassifyEvents classifies the model calls of one session's events (oldest first, as ListEvents returns them).
type CacheLowHit ¶
type CacheLowHit struct {
Step int `json:"step"`
Uncached int64 `json:"uncached_input_tokens"`
Prompt int64 `json:"prompt_tokens"`
HitRate float64 `json:"hit_rate"`
Events []string `json:"events,omitempty"` // events between the previous call and this one
}
CacheLowHit is one steady call whose hit rate stayed below SteadyLowHitBelow: where the next investigation of the hit rate starts.
type Entry ¶
type Entry struct {
SessionID string
Seq int64
TurnID string
Type string
JSON json.RawMessage
CreatedAt time.Time
// contains filtered or unexported fields
}
Entry is one record of a session's linear log. Seq is assigned by the store.
type EntryFilter ¶
type EntryFilter struct {
SinceSeq int64 // only entries with seq > SinceSeq
TurnID string
Types []string
Limit int
// NoHydrate returns the stubs as stored instead of reading the moved bodies
// back from the session file. Use it when only the Content or the metadata of
// the entries is read (an assistant stub keeps the whole Content, a tool stub
// keeps the call id/name), and call Store.HydrateEntries for the entries that
// do go on to a reader that needs the full body.
NoHydrate bool
}
EntryFilter narrows ListEntries; zero values mean no restriction.
type EntryRef ¶
EntryRef is the minimal entry data a reader needs to link events to entries: the call id (tool call or result), the turn, the type and the time, without the entry body. The trace page joins the events of an incremental load against the whole session this way, without sending or parsing the bodies it already showed.
type EntrySearch ¶
type EntrySearch struct {
// Query is split on whitespace; every term must occur (AND). Terms are
// literal text: FTS5 syntax characters have no special meaning.
Query string
// SessionIDs restrict the search to these sessions; empty means all.
SessionIDs []string
// CWDPrefix keeps only sessions whose cwd starts with it (plain string
// prefix, case-sensitive); empty means no restriction.
CWDPrefix string
// WorkspaceDir restricts sessions to this directory and its descendants.
// The comparison is on path-separator boundaries; an empty cwd is excluded.
WorkspaceDir string
// CurrentSessionID is always included with WorkspaceDir, even when that
// session has no cwd. With no WorkspaceDir it restricts results to this ID.
CurrentSessionID string
// FoldCase applies SQLite's ASCII-only lower() folding to the workspace
// comparison. Ledger enables it on Windows to match the approved semantics.
FoldCase bool
// Limit caps the hits: <=0 means 20, at most 100.
Limit int
// IncludeAgents searches sub-agent sessions too (they belong to their
// parent session and are left out by default).
IncludeAgents bool
// Kinds restricts results to indexed entry roles. An empty slice means all
// indexed roles; values must be user, assistant, tool, compaction or
// handoff. tool only matches rows an older index left behind (tool results
// are no longer indexed).
Kinds []string
// Since is an inclusive lower bound on entry creation time. Zero means no
// lower bound.
Since time.Time
// Until is an exclusive upper bound on entry creation time. Zero means no
// upper bound.
Until time.Time
// ExcludeSession drops one session's masked rows (the rows a conversation
// rewind hid) from the hits; other sessions are untouched. The zero value
// excludes nothing, which is what sugasdk and the CLI search with.
ExcludeSession ExcludeSession
// Cursor is a process-local snapshot position. Invalid or expired cursors
// are ignored by SearchEntriesPage, which starts a fresh query.
Cursor string
}
EntrySearch is a ledger full-text query.
type Event ¶
type Event struct {
ID int64
SessionID string
TurnID string
Kind string
Name string
Status string
StartedAt time.Time
DurationMs int64
TTFTMs int64
InputTokens int64
OutputTokens int64
CacheReadTokens int64
CacheWriteTokens int64
Error string
Attrs map[string]any
}
Event is one observability record (model call, tool call, turn ...).
type EventFilter ¶
type EventFilter struct {
SessionID string
// WithAgents widens SessionID to its sub-agent sessions too.
WithAgents bool
TurnID string
Kinds []string
Since time.Time
Limit int
// ByID orders by ID instead of started_at, and AfterID (when > 0) keeps only
// events with ID > AfterID: a stable cursor for paging.
ByID bool
AfterID int64
}
EventFilter narrows ListEvents; zero values mean no restriction.
type ExcludeSession ¶ added in v0.54.0
ExcludeSession drops one session's masked rows from a search (EntrySearch. ExcludeSession). The zero value excludes nothing: sugasdk and the CLI search as before.
type ForkInput ¶ added in v0.54.0
type ForkInput struct {
Session Session
// Turns are stored with their own StartedAt/EndedAt/status; an empty
// SessionID is filled with Session.ID.
Turns []Turn
// Entries must carry Seq 1..n in order and a CreatedAt.
Entries []NewEntry
}
ForkInput is the complete payload of a forked session (session rewind design 0.2, R6). The caller maps everything beforehand: new turn ids, entries renumbered 1..n with their original CreatedAt, compaction and clear records pointing at the new seqs.
type GCReport ¶
type GCReport struct {
// Sessions last updated before the cutoff and not kept (newest first).
Sessions []Session
// Events counts the observability rows removed with those sessions plus
// older rows whose session no longer exists.
Events int64
// SnapshotBytes is the on-disk size of snapshots below the sessions removed
// by this report. It is populated by the CLI, which owns that file root.
SnapshotBytes int64
// Applied is false for a dry run.
Applied bool
}
GCReport is what a garbage collection removes, or would remove on a dry run.
type GCRetentionClassReport ¶
type GCRetentionClassReport struct {
// Interactive names the class and Retention is the period applied to it.
Interactive bool
Retention time.Duration
// Sessions are the sessions of the class this pass removes (or would).
Sessions []Session
// Entries counts all stored entries of those sessions.
Entries int64
// EstimatedBytes approximates the stored bytes they hold: the entry JSON
// bodies plus the session meta. It is an estimate - snapshots, the events
// and the free pages of the file are not counted, and only a VACUUM
// returns space to the disk.
EstimatedBytes int64
}
GCRetentionClassReport is what one retention class of a retention pass removes, or would remove on a dry run.
type GCRetentionPolicy ¶
type GCRetentionPolicy struct {
// Interactive applies to chat sessions and to sessions created before
// meta.origin existed; NonInteractive to run, ACP and sub-agent sessions.
Interactive time.Duration
NonInteractive time.Duration
}
GCRetentionPolicy is the per-class session retention of `suga data gc --retention`. A period of zero or less turns its class off: those sessions are kept.
type GCRetentionReport ¶
type GCRetentionReport struct {
Interactive GCRetentionClassReport
NonInteractive GCRetentionClassReport
// Applied is false for a dry run.
Applied bool
}
GCRetentionReport is the result of a retention pass, one entry per class.
func (GCRetentionReport) Classes ¶
func (r GCRetentionReport) Classes() []GCRetentionClassReport
Classes lists both classes, interactive first.
func (GCRetentionReport) Sessions ¶
func (r GCRetentionReport) Sessions() []Session
Sessions lists every session the pass removes, interactive first.
type MemoryHit ¶
MemoryHit is a ranked hit from memory_fts. The adapter fills the entry's title and kind from the same enumeration used to build the source rows.
type MemoryMeta ¶
type MemoryMeta struct {
Backend, Scope, EntryID string
UUID string
SessionID, TurnID string
Source string
Tainted bool
DeletedAt time.Time
Fingerprint string
CreatedAt, UpdatedAt time.Time
}
MemoryMeta is one memory_meta row (stats, export and tests).
type MemoryRef ¶ added in v0.52.0
type MemoryRef struct {
Backend, Scope, EntryID, UUID string
}
MemoryRef locates a live memory entry by its stable UUID.
type MemorySource ¶
MemorySource is one files-backed entry projected into the derived FTS index. Text is deliberately supplied by the caller: Markdown remains the source of truth and the store only owns the rebuildable SQLite projection.
type ModelStat ¶
type ModelStat struct {
Provider string `json:"provider"`
Model string `json:"model"`
Calls int `json:"calls"`
EstimatedCalls int `json:"estimated_calls,omitempty"`
Errors int `json:"errors"`
ErrorRate float64 `json:"error_rate"`
P50Ms int64 `json:"p50_ms"`
P95Ms int64 `json:"p95_ms"`
P50TTFTMs int64 `json:"p50_ttft_ms,omitempty"`
InputTokens int64 `json:"input_tokens"`
OutputTokens int64 `json:"output_tokens"`
CacheRead int64 `json:"cache_read_tokens"`
CacheWrite int64 `json:"cache_write_tokens"`
CacheHitRate float64 `json:"cache_hit_rate"`
CostUSD float64 `json:"cost_usd"`
}
ModelStat aggregates kind=model events of one provider/model pair. InputTokens follows the REPORTING convention (cache excluded, see personal.ReportUsage): stored input minus cache read/write, floored at 0 per event. CacheHitRate = cache_read / (input + cache_read + cache_write).
type NamedStat ¶
type NamedStat struct {
Name string `json:"name"`
Rows int64 `json:"rows,omitempty"`
Bytes int64 `json:"bytes"`
}
NamedStat is one row of a breakdown (an entry type, an event kind, a JSON field, a tool name).
type NewEntry ¶
type NewEntry struct {
TurnID string
Type string
JSON json.RawMessage
// Seq and CreatedAt are read only by CreateForkedSession, where the caller
// maps them beforehand; AppendEntries assigns both itself and ignores them.
Seq int64
CreatedAt time.Time
}
NewEntry is the input form of Entry for AppendEntries.
type Option ¶
type Option func(*Store)
Option adjusts what a Store knows besides its database file.
func WithSessionsDir ¶
WithSessionsDir sets the sessions root that holds the tool body files (default: <db dir>/../sessions).
func WithToolBodyInlineBytes ¶
WithToolBodyInlineBytes sets the tool body threshold (default 1024, 0 keeps every body inline).
type Report ¶
type Report struct {
Models []ModelStat `json:"models"`
Tools []ToolStat `json:"tools"`
Compactions int `json:"compactions"`
ToolSearch int `json:"tool_searches"`
// FailedAttempts counts provider attempts omitted from cache buckets because
// they failed or reported no token usage.
FailedAttempts int `json:"failed_attempts,omitempty"`
// CacheBuckets splits the model calls by cache bucket (see CacheBucket*).
// BuildReport leaves it nil - its SQL pass is bucket-blind - and the stats
// command fills it from BuildCacheBuckets, so a caller that wants only the
// model and tool rows pays nothing for it.
CacheBuckets []CacheBucketStat `json:"cache_buckets,omitempty"`
}
Report is the result of `suga inspect stats`.
func AggregateEvents ¶
AggregateEvents is the pure aggregation behind BuildReport; the SQL report must keep producing the same result (TestBuildReportMatchesAggregateEvents).
type RewindRecord ¶ added in v0.54.0
type RewindRecord struct {
// Seq is the record's own seq; the masked interval is (CutSeq, Seq).
Seq int64
// CutSeq is the seq of the last entry kept before the rewound turn.
CutSeq int64
TargetTurn string
Scope string
}
RewindRecord is one stored EntryRewind record.
type SearchResult ¶
SearchResult contains one page and the optional continuation metadata. Notice is informational: a stale cursor or a snapshot truncated at 500 hits never turns a valid search into an error.
type SeqRange ¶ added in v0.54.0
type SeqRange struct{ Lo, Hi int64 }
SeqRange is the open interval (Lo, Hi): the seqs Lo < seq < Hi are masked, Lo and Hi themselves are not.
type SeqRanges ¶ added in v0.54.0
type SeqRanges []SeqRange
SeqRanges is a sorted list of disjoint masked intervals; build it with NewSeqRanges. The zero value masks nothing.
func NewSeqRanges ¶ added in v0.54.0
NewSeqRanges sorts rs, drops the intervals that mask no integer (Hi-Lo <= 1) and merges overlapping ones. (1,5) and (4,9) merge into (1,9); (1,5) and (5,9) stay apart because seq 5 is masked by neither.
func RangesOf ¶ added in v0.54.0
func RangesOf(recs []RewindRecord) SeqRanges
RangesOf is the masked intervals of a session's rewind records.
type Session ¶
type Session struct {
ID string
Title string
Cwd string
Status string
LastTurnID string
CreatedAt time.Time
UpdatedAt time.Time
Meta map[string]any
}
Session is one conversation. Meta holds free-form keys (rules hash, append prompt, effective model, loaded deferred tools, usage ...).
type SizeStat ¶
type SizeStat struct {
Rows int64 `json:"rows,omitempty"`
Files int64 `json:"files,omitempty"`
Bytes int64 `json:"bytes"`
}
SizeStat is a row or file count with the bytes it occupies. Rows counts ledger records, Files counts files on disk; a section fills the one that applies.
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store wraps the shared *sql.DB of the core store.
func Open ¶
Open opens (creating if needed) the store at path and applies pending migrations. Repeated opens are idempotent.
func OpenReadOnly ¶
OpenReadOnly opens an existing store for reading only: it never creates the file, never migrates and never writes. A missing file or a database without the migration ledger (an empty or foreign file) is reported as an error, so a read-only page cannot touch a session store it merely is asked to show.
func (*Store) AgentStorage ¶
func (s *Store) AgentStorage() *AgentStorage
AgentStorage returns the agentcore storage adapter for this store.
func (*Store) AppendEntries ¶
func (s *Store) AppendEntries(ctx context.Context, sessionID string, in ...NewEntry) ([]Entry, error)
AppendEntries appends a batch to the session log in one transaction and returns the stored entries with their assigned seq (contiguous, per session).
A tool or assistant entry whose body is larger than store.body_inline_bytes moves into the session body file (tools.jsonl or bodies.jsonl) inside this transaction (design 0.3): the row, the record and the swap to the stub commit together, and a failure of the file write rolls the transaction back after truncating the file to the length it had. The returned entries keep the full body. An assistant entry moves only when its stub saves more than the threshold (design 2026-10-20, revision 8): a big Content without large Reasoning/Metadata stays inline, since the stub has to keep the Content anyway.
func (*Store) AppendEvent ¶
AppendEvent inserts one event and returns it with its assigned ID.
func (*Store) BackfillMemoryUUIDs ¶ added in v0.52.0
BackfillMemoryUUIDs fills UUIDs on rows from databases created before the UUID migration. It runs in one transaction so opening a large store is safe.
func (*Store) BuildCacheBuckets ¶
func (s *Store) BuildCacheBuckets(ctx context.Context, f EventFilter, lowHitLimit int) (CacheBuckets, error)
BuildCacheBuckets classifies the model calls matching f and aggregates them per cache bucket. The buckets are per session: the cold bucket is a session's own first call, so the query is grouped by session id and the rows of one session reach the classifier in time order. lowHitLimit caps the listed steady low-hit calls (0 lists none).
func (*Store) BuildReport ¶
BuildReport queries events matching f (session/since) and aggregates them in SQL: GROUP BY/COUNT/SUM for the totals and one windowed pass per group kind for the nearest-rank percentiles. The result equals AggregateEvents over the same events (TestBuildReportMatchesAggregateEvents), but a report over a large ledger no longer pulls every event through Go and JSON-decodes its attrs.
func (*Store) Close ¶
Close releases the database handle. A shared handle closes with its last store; closing twice is harmless.
func (*Store) CollectGarbage ¶
func (s *Store) CollectGarbage(ctx context.Context, cutoff time.Time, keep map[string]bool, apply bool) (GCReport, error)
CollectGarbage removes sessions not updated since cutoff (and the sub-agent sessions they started), with their turns and entries (ON DELETE CASCADE) and their events, plus events older than cutoff that belong to no session. keep lists session IDs never removed (sessions with a live process). Without apply nothing is written.
The removal runs in batches of gcBatchSessions sessions, each in its own short write transaction, so a cleanup of hundreds of sessions can be interrupted with Ctrl-C and keeps what it already committed. It does NOT VACUUM: returning the freed space to the disk is the explicit `suga data vacuum`, which reports separately from the deleted rows (design 0.3, P3).
func (*Store) CollectGarbageByRetention ¶
func (s *Store) CollectGarbageByRetention(ctx context.Context, now time.Time, policy GCRetentionPolicy, keep map[string]bool, apply bool) (GCRetentionReport, error)
CollectGarbageByRetention removes the sessions whose class retention period has passed. keep lists the sessions never removed (a live process or a held lock). Without apply nothing is written.
func (*Store) CountEntriesByType ¶
CountEntriesByType counts a session's entries of one type. The query is a range scan of that session's primary-key rows with the type filter, never a walk of the whole entries table.
func (*Store) CountEntriesByTypeSkipping ¶ added in v0.54.0
func (s *Store) CountEntriesByTypeSkipping(ctx context.Context, sessionID, typ string, skip SeqRanges) (int, error)
CountEntriesByTypeSkipping is CountEntriesByType over the entries outside skip. It is CountEntriesByType minus the masked rows, in one query that keeps the plain count's plan (idx_entries_type: the rows of one type are few); a per-segment primary-key range count read every row of the session instead (3ms against 30us on 20k entries). An empty skip is CountEntriesByType.
func (*Store) CountTurns ¶
CountTurns counts a session's turns (idx_turns_session, no table scan). It reads the index only: a turn's state_json is never loaded.
func (*Store) CountTurnsSkipping ¶ added in v0.54.0
func (s *Store) CountTurnsSkipping(ctx context.Context, sessionID string, skip SeqRanges) (int, error)
CountTurnsSkipping counts a session's turns outside the masked intervals skip. A turn is masked when it has entries and all of them are masked; a turn with no entry at all counts as before. It is CountTurns when skip is empty.
func (*Store) CreateForkedSession ¶ added in v0.54.0
CreateForkedSession writes the session, its turns and its entries in one write transaction. Entries go through the same in-transaction path as AppendEntries (insertEntryTx), so a fork row is indexed in entries_fts and a big tool or assistant body moves to the new session's body file exactly as it would in a normal append, with the original created_at kept. Any failure rolls the transaction back and drops the body file this call created, so a failed fork leaves neither rows nor files behind. The seq check (1..n, contiguous) runs before the transaction opens.
func (*Store) CreateSession ¶
CreateSession inserts a new session. Empty Status defaults to open and zero timestamps to now.
func (*Store) CreateTurn ¶
CreateTurn inserts a turn. Status defaults to running, StartedAt to now.
func (*Store) DeleteSession ¶
DeleteSession removes a session with its turns and entries (ON DELETE CASCADE). Events are kept: they have no foreign key and record spent tokens.
func (*Store) DeleteSessionFiles ¶
DeleteSessionFiles removes the files of sessions the ledger no longer has (called by the catalogues that delete a session outside `data gc`, which removes the whole session directory itself).
func (*Store) EnsureMemoryUUID ¶ added in v0.52.0
func (s *Store) EnsureMemoryUUID(ctx context.Context, backend string, sc memory.Scope, id string) (string, error)
EnsureMemoryUUID creates the metadata for an old live entry that predates UUIDs. If an ID currently points at a tombstone, that row is archived first.
func (*Store) EntriesAround ¶ added in v0.52.0
func (s *Store) EntriesAround(ctx context.Context, sessionID string, seq int64, window int) ([]Entry, error)
EntriesAround returns the target entry and up to window entries on either side, ordered by the stable session sequence. Entry rows are append-only: AppendEntries assigns the next sequence, while session deletion is the only production path that removes entries (through the sessions foreign-key cascade); no path renumbers an existing sequence.
func (*Store) EntriesFromSkipping ¶ added in v0.54.0
func (s *Store) EntriesFromSkipping(ctx context.Context, sessionID string, types []string, fromSeq int64, skip SeqRanges, limit int) ([]Entry, error)
EntriesFromSkipping returns up to limit entries of the given types with seq >= fromSeq outside skip, oldest first: the window read of recall. Empty types return nothing (as RecentEntries); the caller asks for one row more than it shows when it needs the seq the next window continues from.
func (*Store) FTSShrinkPending ¶
FTSShrinkPending reports whether the ledger still holds tool rows in the index: the search notice tells the model that a search covers user and AI messages only once those rows are gone. It is asked once per store handle (see noteShrinkPending), so the row scan is not run on every search.
func (*Store) GetSession ¶
GetSession returns the session or ErrSessionNotFound.
func (*Store) HasSearchableEntries ¶
HasSearchableEntries reports whether the scope of q holds any searchable entry at all (an indexed type with text): when it does not, no wording can match anything here, and the caller says so instead of letting the model try one query after another (suag-hpu7). Query, Limit, Cursor, Since and Until are ignored; SessionIDs, WorkspaceDir, CurrentSessionID, FoldCase, Kinds and IncludeAgents pick the scope exactly as SearchEntriesPage does. The retrieval tools' own transcripts count as entries here (only excluding them from a match is cheap to skip), so a ledger holding nothing else reports true.
func (*Store) HydrateEntries ¶
HydrateEntries replaces the stubs among entries with the bodies their records hold; entries that are inline stay as they are. Callers that list entries without their bodies (EntryFilter.NoHydrate) use it to fetch exactly the ones they send on. A session without a stub in entries costs no file access.
func (*Store) IsTombstoned ¶
func (s *Store) IsTombstoned(ctx context.Context, backend string, sc memory.Scope, fingerprint string) (bool, error)
IsTombstoned implements memory.ProvenanceStore.
func (*Store) LastEntryAt ¶
LastEntryAt is the time of a session's newest entry (the zero time when the session has none). The primary key makes this a single index read plus the row it points at.
func (*Store) LastEntrySeq ¶ added in v0.52.0
LastEntrySeq returns the highest entries seq of the session, 0 when it has none. A segment record that keeps nothing starts after it (--clear-ctx).
func (*Store) LatestEntry ¶
LatestEntry returns the highest-seq entry of the given type, or (nil, nil) when the session has none.
func (*Store) LatestEntrySkipping ¶ added in v0.54.0
func (s *Store) LatestEntrySkipping(ctx context.Context, sessionID, typ string, skip SeqRanges) (*Entry, error)
LatestEntrySkipping is LatestEntry over the entries outside skip, or (nil, nil) when none is visible.
func (*Store) ListEntries ¶
ListEntries returns entries ordered by seq, narrowed by f.
func (*Store) ListEntryRefs ¶
ListEntryRefs returns the link fields of every entry of a session, oldest first, with the bodies left in the store (see EntryRef).
func (*Store) ListEvents ¶
ListEvents returns events oldest first (started_at, id), narrowed by f.
func (*Store) ListSessions ¶
ListSessions returns all sessions, most recently updated first.
func (*Store) ListTurns ¶
func (s *Store) ListTurns(ctx context.Context, sessionID string, statuses ...string) ([]Turn, error)
ListTurns returns a session's turns oldest first, optionally filtered by status.
func (*Store) MemoryMetaRows ¶
func (s *Store) MemoryMetaRows(ctx context.Context, backend string, sc memory.Scope) ([]MemoryMeta, error)
MemoryMetaRows lists the rows of one backend and scope ordered by entry id.
func (*Store) MemoryRefByUUID ¶ added in v0.52.0
MemoryRefByUUID resolves only live rows; tombstones remain auditable through MemoryMetaRows but cannot be used to mutate a deleted memory entry.
func (*Store) MoveAssistantBodies ¶
func (s *Store) MoveAssistantBodies(ctx context.Context, opts ToolBodyMaintOptions) (ToolBodyMaintReport, error)
MoveAssistantBodies moves historical assistant bodies with an independent checkpoint.
func (*Store) MoveToolBodies ¶
func (s *Store) MoveToolBodies(ctx context.Context, opts ToolBodyMaintOptions) (ToolBodyMaintReport, error)
MoveToolBodies moves the historical tool bodies into the session files, at most Batch rows (or toolBodyBatchBytes) per write transaction, resumable through a (session_id, seq) checkpoint. Rows that are stubs already are skipped, so a rerun continues and an interrupted batch is repeated safely.
func (*Store) PatchSessionMeta ¶
PatchSessionMeta merges patch into meta_json atomically (a nil value deletes the key), so concurrent processes cannot roll back each other's keys.
func (*Store) PatchSessionMetaIfAbsent ¶
func (s *Store) PatchSessionMetaIfAbsent(ctx context.Context, id, guard string, patch map[string]any) (bool, error)
PatchSessionMetaIfAbsent applies patch only when meta has no guard key yet, in the same transaction as the check, so concurrent writers cannot both apply it (write-once keys such as tainted_at). It reports whether the patch was applied.
func (*Store) RecentEntries ¶
func (s *Store) RecentEntries(ctx context.Context, sessionID string, types []string, limit int) ([]Entry, error)
RecentEntries returns the newest entries of the given types, newest first, at most limit of them (nil when the session has none). It walks the (session_id, seq) primary key backwards and stops after limit rows, so a session with a very long log still answers from a few index reads.
func (*Store) RecentEntriesSkipping ¶ added in v0.54.0
func (s *Store) RecentEntriesSkipping(ctx context.Context, sessionID string, types []string, skip SeqRanges, limit int) ([]Entry, error)
RecentEntriesSkipping is RecentEntries over the entries outside the masked intervals skip (newest first, at most limit). It walks the visible segments from the newest, one (session_id, seq) primary-key range query each, and stops when limit rows are found: a large masked interval at the tail costs one empty range read, not a walk over its rows. An empty skip is one query, the same as RecentEntries.
func (*Store) Record ¶
func (s *Store) Record(ctx context.Context, backend string, sc memory.Scope, e memory.Entry, fingerprint string) error
Record implements memory.ProvenanceStore: it upserts the provenance of an added or replaced entry and clears any tombstone of the same id.
Ids are reused (an add may get the id of an entry removed earlier), but the primary key holds one row per id. So before the live row replaces a tombstone, the tombstone is archived under "<id>@<fingerprint prefix>" in the same transaction; IsTombstoned keeps matching it by fingerprint, and its UUID remains available for audit and migration checks.
func (*Store) RemoveToolBodyFiles ¶
RemoveToolBodyFiles deletes the session files of sessions that keep no stub, each confirmed under the write lock so a writer that moved a body out in the meantime is not robbed of its file. It is the --undo --remove-files step.
func (*Store) ResetToolBodyState ¶
ResetToolBodyState drops both checkpoints (--abort): the next pass starts at the first row again.
func (*Store) RewindRecords ¶ added in v0.54.0
func (*Store) SearchEntries ¶
SearchEntries preserves the pre-cursor API for callers that only need hits. The page-aware API is SearchEntriesPage; it owns snapshot creation and continuation metadata.
func (*Store) SearchEntriesPage ¶
func (s *Store) SearchEntriesPage(ctx context.Context, q EntrySearch) (SearchResult, error)
SearchEntriesPage returns one bounded page from a stable process-local snapshot. The SQL runs only when Cursor is empty or its snapshot is stale; valid continuation cursors slice the stored hits and preserve their original snippets and ordering.
func (*Store) SearchMemoryIndex ¶
func (s *Store) SearchMemoryIndex(ctx context.Context, scope, q string, limit int) ([]MemoryHit, error)
SearchMemoryIndex searches one scope with the same trigram/short-term split as session search. Long terms use FTS5 bm25 ranking; one- and two-rune terms remain LIKE filters so CJK and short identifiers are still searchable.
func (*Store) SessionCwds ¶
SessionCwds returns id -> cwd of every session with a recorded cwd. It reads only those two columns (meta_json can be large), for callers that match paths themselves (e.g. with path-separator boundaries).
func (*Store) SetToolBodyMove ¶
SetToolBodyMove writes the persistent switch: false keeps every new tool body inline until a later `--move` turns it on again.
func (*Store) Snapshot ¶
Snapshot writes a transactionally consistent SQLite snapshot to destination. VACUUM INTO is deliberately explicit: it never copies a live WAL or SHM file.
func (*Store) SumUsage ¶
SumUsage totals tokens over kind=model events only; turn/tool events carry no per-call usage of their own, so nothing is counted twice. Cost is the sum of the optional attrs.cost_usd of those events.
func (*Store) SumUsageTree ¶
SumUsageTree is SumUsage over the session and its sub-agent sessions (meta parent_session_id = sessionID): what the session spent in all, as its cumulative usage reports it.
func (*Store) SyncMemoryIndex ¶
func (s *Store) SyncMemoryIndex(ctx context.Context, scope string, sources []MemorySource) (added, removed int, err error)
SyncMemoryIndex incrementally makes memory_fts match sources for scope. A single transaction makes a search see either the old projection or the new one; changed rows are deleted before insertion because FTS5 has no ordinary UPDATE semantics for its UNINDEXED metadata columns.
func (*Store) Tombstone ¶
func (s *Store) Tombstone(ctx context.Context, backend string, sc memory.Scope, id, fingerprint string) error
Tombstone implements memory.ProvenanceStore: it marks the entry removed and stores the fingerprint of the removed content. An empty fingerprint keeps the one recorded with the entry. Entries without a provenance row get a UUID now, so a later ID reuse cannot erase this tombstone's identity.
func (*Store) ToolBodyCheck ¶
func (s *Store) ToolBodyCheck(ctx context.Context) (ToolBodyCheckReport, error)
ToolBodyCheck verifies every stub and reports what does not line up. It only reads: a missing body or an orphan record is left for the operator (restore from a backup, or --undo when the file is still complete).
func (*Store) ToolBodyStatus ¶
func (s *Store) ToolBodyStatus(ctx context.Context) (ToolBodyStatus, error)
ToolBodyStatus reports what is left to move, what moved and how large the session files are.
func (*Store) UndoToolBodies ¶
func (s *Store) UndoToolBodies(ctx context.Context, opts ToolBodyMaintOptions) (ToolBodyMaintReport, error)
UndoToolBodies restores every moved body into the ledger and disables new moves.
func (*Store) UpdateEventEntrySeq ¶
UpdateEventEntrySeq fills the sequence of a pending injected entry after the next turn stores it. The event is written when undo completes, while the entry itself is deliberately deferred until the user starts another turn.
func (*Store) UpdateSession ¶
UpdateSession overwrites title, cwd, status, last_turn_id and meta of an existing session. UpdatedAt defaults to now when zero.
func (*Store) UpdateSessionFields ¶
UpdateSessionFields sets title, cwd, status, last_turn_id and updated_at of an existing session and leaves its meta alone. Meta is patched by key (PatchSessionMeta, PatchSessionMetaIfAbsent) by several writers, e.g. a background task marking the session tainted while a turn runs; writing back a meta read earlier (UpdateSession) would drop what they added meanwhile. UpdatedAt defaults to now when zero.
func (*Store) UpdateTurn ¶
UpdateTurn writes status, stop_reason and ended_at (state_json is owned by UpsertTurnState and left untouched).
func (*Store) UpsertTurnState ¶
UpsertTurnState stores the agentcore RunState snapshot of an existing turn.
func (*Store) Usage ¶
func (s *Store) Usage(ctx context.Context, opts UsageOptions) (UsageReport, error)
Usage builds the storage report. It reads through s, so it must be a read-only store; no statement writes.
func (*Store) Vacuum ¶
func (s *Store) Vacuum(ctx context.Context) (VacuumResult, error)
Vacuum rewrites the database file so that the space freed by deletions and the FTS shrink returns to the disk, then truncates the WAL. It needs roughly as much free space as the file is large (SQLite writes a new file and swaps it in), so the caller checks that first. The store must not be used from another process while it runs: VACUUM rewrites every page.
type ToolBodyCheckReport ¶
type ToolBodyCheckReport struct {
// Checked is the number of stub rows verified, Missing those whose body could
// not be read back (the ledger points at nothing valid).
Checked int64
Missing int64
// OrphanRecords are records no stub points at (a crash before the commit of a
// moved body leaves one), OrphanBytes their size.
OrphanRecords int64
OrphanBytes int64
// Problems lists the first few failures, for the operator to see.
Problems []string
}
ToolBodyCheckReport is what --check found. It only reports: cleaning an orphan record would rewrite the file and move every offset after it, which has to happen under the write lock with the stubs, and is left out of this version.
func (ToolBodyCheckReport) OK ¶
func (r ToolBodyCheckReport) OK() bool
OK reports whether the ledger and its files agree.
type ToolBodyMaintOptions ¶
type ToolBodyMaintOptions struct {
Batch int
OnBatch func(ToolBodyMaintProgress)
}
ToolBodyMaintOptions configures one pass. The zero value is the CLI default.
type ToolBodyMaintProgress ¶
type ToolBodyMaintProgress struct {
// SessionID and Seq are the cursor after the batch.
SessionID string
Seq int64
// Rows and Bytes are the totals of the pass so far.
Rows int64
Bytes int64
}
ToolBodyMaintProgress is one finished batch.
type ToolBodyMaintReport ¶
type ToolBodyMaintReport struct {
Rows int64
Bytes int64
Batches int
// CursorSession and CursorSeq are the checkpoint the pass reached; Complete is
// false only when the caller stopped it with ctx.
CursorSession string
CursorSeq int64
Complete bool
}
ToolBodyMaintReport describes what one pass did.
type ToolBodyStatus ¶
type ToolBodyStatus struct {
// InlineBytes is the threshold in force; MoveEnabled is the persistent switch
// (false after --undo).
InlineBytes int64
MoveEnabled bool
// PendingRows and PendingBytes are the tool rows that would still move;
// AssistantPending* the same for assistant entries (the migration of revision
// 3, an independent pass). AssistantSkippedRows (and its bytes) are the SQL
// candidates the assistant pass leaves alone because moving them out saves no
// more than the threshold: counted apart so --status does not ask for a --move
// run that cannot do anything.
PendingRows int64
PendingBytes int64
AssistantPendingRows int64
AssistantPending int64
AssistantSkippedRows int64
AssistantSkipped int64
// MovedRows are the rows whose body lives in a file, FileBytes and Files what
// the session files hold (both file names).
MovedRows int64
AssistantMovedRows int64
FileBytes int64
Files int
// BodyFileNameEnabled is the file name switch (set by v0.40's --rename-files);
// LegacyNameFiles counts the sessions still holding a tools.jsonl file. Both
// are read-only information: this version writes whichever name the switch
// names, so a renamed ledger keeps working.
BodyFileNameEnabled bool
LegacyNameFiles int
// The checkpoints of both passes.
MoveStarted, MoveComplete bool
MoveSession string
MoveSeq, MoveRows int64
AssistantMoveStarted bool
AssistantMoveComplete bool
AssistantMoveSession string
AssistantMoveSeq int64
AssistantMoveRows int64
UndoStarted, UndoComplete bool
UndoRows int64
}
ToolBodyStatus is what --status reports.
type ToolStat ¶
type ToolStat struct {
Name string `json:"name"`
Calls int `json:"calls"`
Errors int `json:"errors"`
ErrorRate float64 `json:"error_rate"`
Denials int `json:"denials"`
P50Ms int64 `json:"p50_ms"`
P95Ms int64 `json:"p95_ms"`
// RawBytes / InlineBytes sum the tool output produced and the part kept in
// the session (event attrs raw_bytes / inline_bytes); Spilled counts calls
// whose full output was saved to the session directory.
RawBytes int64 `json:"raw_bytes"`
InlineBytes int64 `json:"inline_bytes"`
Spilled int `json:"spilled"`
}
ToolStat aggregates tool events by tool name. Calls counts executed tool events; denial events (which replace the tool event when approval refuses a call) are counted in Denials only.
type Turn ¶
type Turn struct {
ID string
SessionID string
Status string
StopReason string
StateJSON []byte // agentcore RunState snapshot; empty until SaveRun
StartedAt time.Time
EndedAt time.Time
}
Turn is one user request and its agentcore run (run_id == turn id).
type Usage ¶
type Usage struct {
Calls int64
InputTokens int64
OutputTokens int64
CacheReadTokens int64
CacheWriteTokens int64
CostUSD float64
}
Usage is the token total returned by SumUsage.
type UsageAssistant ¶
type UsageAssistant struct {
Rows int64 `json:"rows"`
Bytes int64 `json:"bytes"`
Fields []NamedStat `json:"fields"`
MetadataKeys []NamedStat `json:"metadata_keys"`
Tools []NamedStat `json:"tool_arguments"`
}
UsageAssistant splits the assistant entries, which carry the bulk of the ledger: their JSON fields, the metadata keys and the tool call arguments. The numbers describe what is still inside the ledger; a row whose body moved to a session file only counts the stub (see UsageEntries.MovedAssistant).
type UsageEntries ¶
type UsageEntries struct {
Rows int64 `json:"rows"`
Bytes int64 `json:"bytes"`
Types []NamedStat `json:"types"`
Assistant UsageAssistant `json:"assistant"`
Tool UsageToolEntries `json:"tool"`
// MovedAssistant are the assistant rows whose body lives in a session file
// (entries.body_ref set, only a stub in the ledger). Their Reasoning,
// Metadata and call arguments are in the file, so the Values above no longer
// count them.
MovedAssistant SizeStat `json:"moved_assistant"`
Suggestion string `json:"suggestion,omitempty"`
}
UsageEntries is the entries table by type and by large JSON field.
type UsageEvents ¶
type UsageEvents struct {
Rows int64 `json:"rows"`
Bytes int64 `json:"bytes"`
Kinds []NamedStat `json:"kinds"`
Suggestion string `json:"suggestion,omitempty"`
}
UsageEvents is the events table by kind. Bytes counts attrs_json and error, the two free-form columns.
type UsageFTS ¶
type UsageFTS struct {
Rows int64 `json:"rows"`
Roles []NamedStat `json:"roles"`
DataBytes int64 `json:"data_bytes"`
ContentBytes int64 `json:"content_bytes"`
Bytes int64 `json:"bytes"`
Suggestion string `json:"suggestion,omitempty"`
}
UsageFTS is the entries_fts index: its rows (one per indexed entry) and the bytes of its shadow tables.
type UsageFile ¶
type UsageFile struct {
Path string `json:"path"`
Bytes int64 `json:"bytes"`
PageSize int64 `json:"page_size"`
Pages int64 `json:"pages"`
FreePages int64 `json:"free_pages"`
FreeBytes int64 `json:"free_bytes"`
WALBytes int64 `json:"wal_bytes"`
// Suggestion names the command that acts on this section ("" if none).
Suggestion string `json:"suggestion,omitempty"`
}
UsageFile is the database file itself.
type UsageOptions ¶
type UsageOptions struct {
Top int
// Translator renders human-facing maintenance suggestions. A nil translator
// uses the Chinese fallback for callers predating language injection.
Translator i18n.Translator
}
UsageOptions narrows the usage report. Top bounds every "N largest" list.
type UsageReport ¶
type UsageReport struct {
File UsageFile `json:"file"`
Entries UsageEntries `json:"entries"`
Events UsageEvents `json:"events"`
FTS UsageFTS `json:"fts"`
Sessions UsageSessions `json:"sessions"`
// Tables holds the dbstat page usage (largest first) and DBStat says
// whether this build of SQLite has the virtual table.
Tables []UsageTable `json:"tables,omitempty"`
DBStat bool `json:"dbstat"`
// Top is the N every list was cut at.
Top int `json:"top"`
// TotalBytes is the database file plus the files below the sessions root.
TotalBytes int64 `json:"total_bytes"`
}
UsageReport is the result of `suga data usage`.
type UsageSession ¶
type UsageSession struct {
ID string `json:"id"`
Title string `json:"title,omitempty"`
DBBytes int64 `json:"db_bytes"`
DirBytes int64 `json:"dir_bytes"`
Bytes int64 `json:"bytes"`
}
UsageSession is one session in the "largest" list: its ledger bytes and its directory bytes, summed into Bytes.
type UsageSessions ¶
type UsageSessions struct {
InStore int64 `json:"in_store"`
Dirs int64 `json:"dirs"`
// Tools is every body file of a session, under both names (Tools carries
// tools.jsonl of version 0.36, BodyFiles says how it splits).
Tools SizeStat `json:"tools"`
BodyFiles []NamedStat `json:"body_files"`
Outputs SizeStat `json:"outputs"`
OutputsGz SizeStat `json:"outputs_gz"`
Images SizeStat `json:"images"`
Snapshots SizeStat `json:"snapshots"`
Other SizeStat `json:"other"`
Top []UsageSession `json:"top"`
Suggestion string `json:"suggestion,omitempty"`
}
UsageSessions is the sessions root outside the database: the per-session files and the sessions that hold the most.
type UsageTable ¶
UsageTable is the real page usage of one table or index, from SQLite's dbstat virtual table.
type UsageToolEntries ¶
UsageToolEntries separates tool results that moved to the session file (entries.body_ref set, only a stub in the ledger) from the ones stored inline.
type VacuumResult ¶
type VacuumResult struct {
BytesBefore int64
BytesAfter int64
DBBytesBefore int64
DBBytesAfter int64
WALBytesBefore int64
WALBytesAfter int64
}
VacuumResult reports the database file sizes around a VACUUM. The main file only grows while the data sits in the -wal file, so a caller that wants to show the reclaimed space compares the totals (BytesBefore/BytesAfter).
Source Files
¶
- agentstore.go
- cachebucket.go
- entries.go
- events.go
- fork_store.go
- freespace_unix.go
- fts.go
- fts_cursor.go
- fts_shrink.go
- fts_snapshot.go
- gc.go
- gc_retention.go
- image_files.go
- memfts.go
- memory_meta.go
- message_json.go
- report.go
- rewind_store.go
- session_origin.go
- sessions.go
- snapshot.go
- store.go
- toolbody.go
- toolbody_check.go
- toolbody_maint.go
- toolbody_unix.go
- turns.go
- tx.go
- types.go
- usage.go
- vacuum.go