memory

type Assembly ¶

type Assembly interface {
	ContextProvider
	TurnSink
	DocumentSink
}

Assembly is the memory capability contract a deployment binds to: agent lifecycle hooks consume it as a context provider and turn sink, and applications can push documents. Implementations (such as the flowcraft memory module) build one through their config.Factory implementation and may expose implementation-specific services (like background workers) through their own types; this package knows nothing about them.

type Budget ¶

type Budget struct {
	MaxTokens int
	MaxItems  int
	MaxChars  int
}

Budget bounds context packing. Zero fields select implementation defaults.

func (b Budget) Validate() error

type ContextAddress ¶

type ContextAddress struct {
	Kind           ContextItemKind
	ConversationID string
	DatasetID      string
	DocumentID     string
	ItemID         string
}

ContextAddress qualifies a view-local item ID within one hard scope. Conversation and document coordinates are explicit so equal local IDs in different conversations or datasets remain distinct.

func (address ContextAddress) Identity(scope Scope) string

func (address ContextAddress) IsZero() bool

func (address ContextAddress) Key() string

func (address ContextAddress) Validate() error

type ContextItem ¶

type ContextItem struct {
	ID          string
	Address     ContextAddress
	Kind        ContextItemKind
	Content     message.Content
	Score       float64
	Sources     []SourceRef
	Metadata    Metadata
	TokenCount  int
	SourceClass ContextSourceClass
	MessageRole message.Role
	Sequence    uint64
	Timestamp   time.Time
	ParentID    string
	Level       int
	Ordinal     uint64
	Title       string
	Hint        *ExpandHint
}

ContextItem is a hydrated, scored memory item. Score has one portable meaning across implementations: larger is more relevant and values are in [0,1]. Scores from individual retrieval lanes are implementation details.

func (i ContextItem) Clone() ContextItem

func (i ContextItem) Identity(scope Scope) string

func (i ContextItem) Validate() error

type ContextItemKind ¶

type ContextItemKind string

ContextItemKind identifies a hydrated memory view.

const (
	ContextRawMessage       ContextItemKind = "raw_message"
	ContextFact             ContextItemKind = "fact"
	ContextDocumentResource ContextItemKind = "document_resource"
	ContextDocumentSection  ContextItemKind = "document_section"
	ContextDocumentChunk    ContextItemKind = "document_chunk"
	ContextDocumentSummary  ContextItemKind = "document_summary"
	ContextSummary          ContextItemKind = "summary"
)

func (kind ContextItemKind) Validate() error

type ContextProvider ¶

type ContextProvider interface {
	Context(context.Context, ContextRequest) (ContextResult, error)
}

ContextProvider selects, hydrates, and packs memory for an agent turn. Retrieval indexes and fusion strategies remain implementation details.

type ContextRange ¶

type ContextRange struct {
	StartSequence uint64
	EndSequence   uint64
	StartTime     time.Time
	EndTime       time.Time
}

ContextRange identifies the canonical sequence/time interval represented by a compressed item.

func (value ContextRange) Validate() error

type ContextRenderer ¶

type ContextRenderer interface {
	Render(context.Context, ContextResult) (message.Content, error)
}

ContextRenderer projects a structured context result into content suitable for an agent prompt. It is a consumer-side SPI: memory providers remain responsible only for selecting, hydrating, and packing ContextItems.

type ContextRendererFunc ¶

type ContextRendererFunc func(context.Context, ContextResult) (message.Content, error)

ContextRendererFunc adapts a function to ContextRenderer.

func (function ContextRendererFunc) Render(ctx context.Context, result ContextResult) (message.Content, error)

type ContextRequest ¶

type ContextRequest struct {
	Scope           Scope
	ConversationID  string
	DatasetIDs      []string
	Query           string
	Budget          Budget
	RecentLimit     int
	RecentMaxTokens int
	MinScore        float64
	Metadata        Metadata
	// RecallEventID is a stable invocation/event identity. Providers must not
	// reinforce retrieval when it is empty.
	RecallEventID string
}

func (r ContextRequest) Validate() error

type ContextResult ¶

type ContextResult struct {
	Items         []ContextItem
	TokenCount    int
	Truncated     bool
	RecallEventID string
}

func (r ContextResult) Clone() ContextResult

func (r ContextResult) Validate() error

type ContextSourceClass ¶

type ContextSourceClass string

ContextSourceClass identifies the fixed read-path source without relying on metadata markers.

const (
	ContextSourceRecent   ContextSourceClass = "recent"
	ContextSourceLongTerm ContextSourceClass = "long_term"
	ContextSourceSummary  ContextSourceClass = "summary"
)

func (class ContextSourceClass) Validate() error

type Document ¶

type Document struct {
	Scope          Scope
	DatasetID      string
	DocumentID     string
	IdempotencyKey string
	Content        message.Content
	Provenance     []SourceRef
	Metadata       Metadata
}

func (d Document) Clone() Document

func (d Document) Validate() error

type DocumentSink ¶

type DocumentSink interface {
	PutDocument(context.Context, Document) error
}

DocumentSink durably stores normalized document content and provenance. URI fetching, parsing, and media extraction happen before this boundary.

type Error ¶

type Error struct {
	Kind       ErrorKind
	Capability string
	// contains filtered or unexported fields
}

Error is the implementation-neutral memory error. Capability identifies the narrow SPI surface ("context", "turn", or "document") without exposing implementation stages or storage details.

func AsError(err error) *Error

func NewError(kind ErrorKind, capability string, cause error) *Error

func (e *Error) Error() string

func (e *Error) Unwrap() error

type ErrorKind ¶

type ErrorKind string

ErrorKind classifies failures shared by memory capability implementations.

const (
	KindInvalidRequest       ErrorKind = "invalid_request"
	KindNotConfigured        ErrorKind = "not_configured"
	KindConflict             ErrorKind = "conflict"
	KindOperationInterrupted ErrorKind = "operation_interrupted"
	KindProviderFailure      ErrorKind = "provider_failure"
	KindInternal             ErrorKind = "internal"
)

type ExpandHint ¶

type ExpandHint struct {
	Topics         []string
	SourceRefs     []SourceRef
	Range          ContextRange
	PreferredLevel int
}

ExpandHint is structured navigation metadata. Consumers must resolve its provenance through hydration APIs; it is never prompt text.

func (hint ExpandHint) Clone() ExpandHint

func (hint ExpandHint) Validate() error

type Metadata ¶

type Metadata map[string]string

Metadata is opaque, serializable annotation data. Capability implementations must not use it to weaken Scope's tenant boundary.

func (src Metadata) Clone() Metadata

type RecallEvent ¶

type RecallEvent struct {
	ID      string
	Scope   Scope
	ItemIDs []string
	Time    time.Time
	Scores  []float64
}

RecallEvent records only items actually returned from long-term or summary retrieval. ItemIDs and Scores are parallel canonical arrays.

func (event RecallEvent) Validate() error

type Scope ¶

type Scope struct {
	// RuntimeID names the configured memory resource.
	RuntimeID string
	// UserID is the tenant partition. Empty selects a documented global scope.
	UserID string
	// AgentID is part of the hard partition. Empty selects the explicit
	// global-agent partition; it never widens reads to other agents.
	AgentID string
}

Scope identifies a memory instance and its tenant. Conversation and dataset addresses intentionally live on individual requests so there is only one source of truth for each address.

func (s Scope) HardPartitionKey() string

func (s Scope) IsZero() bool

func (s Scope) String() string

func (s Scope) Validate() error

type SourceKind ¶

type SourceKind string

SourceKind names a canonical source type.

const (
	SourceMessage  SourceKind = "message"
	SourceDocument SourceKind = "document"
	SourceExternal SourceKind = "external"
)

func (kind SourceKind) Validate() error

type SourceRef ¶

type SourceRef struct {
	Kind     SourceKind
	ID       string
	Revision string
	Locator  string
}

SourceRef preserves provenance without exposing a storage backend.

func (r SourceRef) Validate() error

type Turn ¶

type Turn struct {
	Scope          Scope
	ConversationID string
	IdempotencyKey string
	Messages       []message.Message
	Metadata       Metadata
}

func (t Turn) Clone() Turn

func (t Turn) Validate() error

type TurnSink ¶

type TurnSink interface {
	CommitTurn(context.Context, Turn) error
}

TurnSink durably commits canonical conversation messages. Success means the source and its durable derivation work were accepted; asynchronous derivation branch failures do not retroactively fail the commit.