memory

type ContextItem struct {
	ID           string                 `json:"id"`
	EdgeType     string                 `json:"edge_type"`
	Confidence   string                 `json:"confidence"`
	Frontmatter  map[string]interface{} `json:"frontmatter"`
	BodyIncluded bool                   `json:"body_included"`
	// BodyExcerpted marks Body as the note's most decision-relevant passage
	// rather than its whole text. It is recorded rather than inferred because
	// "the agent got the note" and "the agent got the gist" are different facts,
	// and a metric that cannot tell them apart reports the second as the first.
	BodyExcerpted bool   `json:"body_excerpted,omitempty"`
	Body          string `json:"body,omitempty"`
	// ShownBefore marks a note whose body this conversation already received
	// recently. It degrades to its title — never dropped, so an agent that lost
	// the earlier copy to compaction still sees the note exists.
	ShownBefore bool `json:"shown_before,omitempty"`
	// BodyOmittedBudget records a non-empty body excluded by the token budget.
	// Empty or unavailable bodies must never be described as budget losses.
	BodyOmittedBudget bool `json:"body_omitted_budget,omitempty"`
	// BodyRawUnfilled is true when body_raw IS NULL. See ContextPackTarget.
	BodyRawUnfilled bool `json:"-"`
	// AnswersGap is the recorded question this note closed. Present only when
	// this item's body was delivered and the note was not already shown.
	AnswersGap *index.GapCredit `json:"answers_gap,omitempty"`
}

type ContextPackConfig struct {
	Input            string
	Budget           int                // token budget
	Depth            int                // BFS traversal depth; 0 or 1 = direct neighbors only (default)
	MaxItems         int                // max context items to return; 0 = unlimited (default, backward-compat)
	Slim             bool               // reduce context item frontmatter to {type, title, status} only
	ActivationScores map[string]float64 // optional activation scores keyed by note ID

	// ExcerptTokens caps a per-item excerpt used when a whole body will not fit
	// the remaining budget. 0 (default) keeps the released all-or-nothing
	// behaviour, where such an item contributes no text at all.
	//
	// Without this, a pack can honestly report "3 items" while handing the agent
	// nothing but titles — which is what a 900-token hook budget does against a
	// vault whose median note is larger than the budget.
	ExcerptTokens int

	// Seeds are notes the caller already judged relevant — ask passes the
	// search hits after the first that clear the weak band. They are packed
	// ahead of every graph neighbour, in the order given, because a note that
	// matched the question outranks one that is merely linked to the answer.
	Seeds []Seed

	// IncludeDrafts lets a status:draft note be a context item. Off by default,
	// the same switch as ranking. The note the caller named is the target and
	// is packed either way.
	IncludeDrafts bool
}

type ContextPackResult struct {
	TargetID        string             `json:"target_id"`
	BudgetTokens    int                `json:"budget_tokens"`
	UsedTokens      int                `json:"used_tokens"`
	BudgetExhausted bool               `json:"budget_exhausted"`
	Truncated       bool               `json:"truncated"`
	Target          *ContextPackTarget `json:"target"`
	Context         []ContextItem      `json:"context"`
}

type ContextPackTarget struct {
	ID          string                 `json:"id"`
	Frontmatter map[string]interface{} `json:"frontmatter"`
	// BodyExcerpted marks Body as the note's decision-bearing passage rather
	// than its whole text — same meaning as on ContextItem, and needed here for
	// the same reason: a renderer that cannot tell the difference will truncate
	// an already-bounded excerpt a second time.
	BodyExcerpted bool `json:"body_excerpted,omitempty"`
	// BodyCutToBudget is set only when the packer byte-sliced Body to fit the
	// budget. It is not BodyExcerpted (a chosen passage) and not the pack's
	// Truncated flag (also set when the body is empty or there is no room).
	// The ask header reads it so a cut body is not called "delivered in full".
	BodyCutToBudget bool   `json:"body_cut_to_budget,omitempty"`
	Body            string `json:"body,omitempty"`
	// ShownBefore marks a note whose body this conversation already received
	// recently; it is sent as its title alone. See ContextItem.ShownBefore.
	ShownBefore bool `json:"shown_before,omitempty"`
	// BodyOmittedBudget records a non-empty body excluded by the token budget.
	// Empty or unavailable bodies must never be described as budget losses.
	BodyOmittedBudget bool `json:"body_omitted_budget,omitempty"`
	// BodyRawUnfilled is true when body_raw IS NULL. The ask footer suggests
	// re-indexing only then; a stored empty body is not unfilled.
	BodyRawUnfilled bool `json:"-"`
	// AnswersGap is the recorded question this note closed. It is present only
	// when the text line is: the body was delivered, and the note was not
	// already shown. A draft or a gap never carries it.
	AnswersGap *index.GapCredit `json:"answers_gap,omitempty"`
}

type OmittedNote struct {
	ID    string `json:"id"`
	Title string `json:"title"`
	Vault string `json:"vault,omitempty"`
}

type PinnedConfig struct {
	Budget        int
	ExcerptTokens int
}

type PinnedItem struct {
	ID      string `json:"id"`
	Title   string `json:"title"`
	Excerpt string `json:"excerpt"`
	Tokens  int    `json:"tokens"`
	Vault   string `json:"vault,omitempty"`
}

type PinnedResult struct {
	Total   int           `json:"total"`
	Items   []PinnedItem  `json:"items"`
	Omitted []OmittedNote `json:"omitted,omitempty"`
	Tokens  int           `json:"tokens"`
	Budget  int           `json:"budget"`
}

type PinnedVault struct {
	DB    *index.DB
	Vault string
}

type RecallConfig struct {
	Input         string
	Depth         int
	MinConfidence string
	MaxNodes      int
	// IncludeDrafts lets a status:draft note be a neighbor. Off by default.
	// The note the caller named stays the start of the traversal.
	IncludeDrafts bool
}

type RecallEdge struct {
	SourceID   string `json:"source_id"`
	TargetID   string `json:"target_id"`
	EdgeType   string `json:"edge_type"`
	Confidence string `json:"confidence"`
}

type RecallNode struct {
	ID             string                 `json:"id"`
	Type           string                 `json:"type"`
	Title          string                 `json:"title"`
	Distance       int                    `json:"distance"`
	EdgeFromParent *graph.TraverseEdge    `json:"edge_from_parent,omitempty"`
	Frontmatter    map[string]interface{} `json:"frontmatter"`
}

type RecallResult struct {
	TargetID        string       `json:"target_id"`
	Depth           int          `json:"depth"`
	MaxNodes        int          `json:"max_nodes"`
	MaxNodesReached bool         `json:"max_nodes_reached"`
	Nodes           []RecallNode `json:"nodes"`
	Edges           []RecallEdge `json:"edges"`
}

type ReciteConfig struct {
	// Type is the note type to enumerate ("arc").
	Type string
	// Budget is the total token ceiling. 0 means unbounded.
	Budget int
	// ExcerptTokens caps each note's contribution. 0 means whole bodies.
	ExcerptTokens int
	// IncludeDrafts recites a status:draft note. Off by default: a draft arc
	// is a proposal, not identity, until its status changes.
	IncludeDrafts bool
}

type ReciteItem struct {
	ID      string `json:"id"`
	Title   string `json:"title"`
	Excerpt string `json:"excerpt"`
	Tokens  int    `json:"tokens"`
}

type ReciteResult struct {
	Type       string       `json:"type"`
	Total      int          `json:"total"`
	Items      []ReciteItem `json:"items"`
	Omitted    int          `json:"omitted"`
	OmittedIDs []string     `json:"omitted_ids,omitempty"`
	Tokens     int          `json:"tokens"`
	Budget     int          `json:"budget"`
}

type RelatedConfig struct {
	Input string
	Mode  string // "mixed", "explicit", or "inferred"
	// IncludeDrafts lets a status:draft note be listed. Off by default.
	// The note the caller named is the target and is not filtered.
	IncludeDrafts bool
}

type RelatedItem struct {
	ID         string  `json:"id"`
	Type       string  `json:"type"`
	Title      string  `json:"title"`
	EdgeType   string  `json:"edge_type"`
	Confidence string  `json:"confidence"`
	Origin     string  `json:"origin"`
	Score      float64 `json:"score,omitempty"`
}

type RelatedResult struct {
	TargetID string        `json:"target_id"`
	Mode     string        `json:"mode"`
	Related  []RelatedItem `json:"related"`
}

type Seed struct {
	ID         string
	Confidence string
}

type SummarizeConfig struct {
	NoteIDs     []string
	IncludeBody bool
	MaxBodyLen  int // max chars per note body (0 = full)
}

type SummarizeResult struct {
	Sources   []SummarizeSource `json:"sources"`
	NoteCount int               `json:"note_count"`
	NotFound  []string          `json:"not_found,omitempty"`
}

type SummarizeSource struct {
	ID          string                 `json:"id"`
	Type        string                 `json:"type"`
	Title       string                 `json:"title"`
	Frontmatter map[string]interface{} `json:"frontmatter"`
	BodyExcerpt string                 `json:"body_excerpt,omitempty"`
}