contract

Documentation

Overview

Package contract defines the shared Memory v2 data contract.

Index

• Variables
• type AgentTier
  • func (t AgentTier) Normalize() AgentTier
  • func (t AgentTier) Validate() error
• type Backend
• type Block
• type CacheStableHeader
• type Candidate
• type Controller
• type Decision
• type DecisionSource
  • func (s DecisionSource) Normalize() DecisionSource
  • func (s DecisionSource) Validate() error
• type Extractor
• type Header
  • func (h *Header) Normalize()
  • func (h *Header) Validate() error
• type HealthStats
• type LLMCall
• type MemoryProvider
• type Op
  • func (o Op) MarshalJSON() ([]byte, error)
  • func (o Op) Normalize() Op
  • func (o Op) String() string
  • func (o *Op) UnmarshalJSON(data []byte) error
  • func (o Op) Validate() error
• type Operation
  • func (o Operation) Normalize() Operation
• type OperationHistoryQuery
• type OperationRecord
• type Origin
  • func (o Origin) Normalize() Origin
  • func (o Origin) Validate() error
• type Packaged
• type PackagedEntry
• type PreCompressHint
• type PreCompressRequest
• type PrefetchRequest
• type Provenance
  • func (p *Provenance) Normalize()
  • func (p *Provenance) Validate() error
• type ProviderInit
• type Query
• type RecallOptions
• type RecallRequest
• type RecallResult
• type Recaller
• type ReindexOptions
• type ReindexResult
• type RuleHit
• type Scope
  • func DefaultScopeForType(t Type) (Scope, error)
  • func (s Scope) Normalize() Scope
  • func (s Scope) Validate() error
• type SearchOptions
• type SearchResult
• type SessionEndRecord
• type SessionSwitchRecord
• type SnapshotRequest
• type SnapshotResult
• type TranscriptMessage
• type TranscriptSnapshot
• type Trigger
  • func (t Trigger) Normalize() Trigger
  • func (t Trigger) Validate() error
• type TurnRecord
• type Type
  • func (t Type) Normalize() Type
  • func (t Type) Validate() error
• type WriteRecord

Variables

var ErrNotImplemented = errors.New("memory provider: not implemented")

ErrNotImplemented lets optional provider methods request the local fallback.

Types

type AgentTier

type AgentTier string

AgentTier identifies which agent tier owns an agent-scoped memory entry.

const (
	AgentTierWorkspace AgentTier = "workspace"
	AgentTierGlobal    AgentTier = "global"
)

func (AgentTier) Normalize

func (t AgentTier) Normalize() AgentTier

Normalize returns the normalized representation of the agent tier.

func (AgentTier) Validate

func (t AgentTier) Validate() error

Validate reports whether the agent tier belongs to the closed taxonomy.

type Backend

type Backend interface {
	List(scope Scope) ([]Header, error)
	Read(scope Scope, filename string) ([]byte, error)
	Write(scope Scope, filename string, content []byte) error
	Delete(scope Scope, filename string) error
	Search(ctx context.Context, query string, opts SearchOptions) ([]SearchResult, error)
	Reindex(ctx context.Context, opts ReindexOptions) (ReindexResult, error)
	History(ctx context.Context, query OperationHistoryQuery) ([]OperationRecord, error)
	LoadPromptIndex(scope Scope) (content string, truncated bool, err error)
}

Backend captures the memory backend surface used by daemon, API, and CLI layers.

type Block

type Block struct {
	Scope     Scope           `json:"scope"`
	AgentTier AgentTier       `json:"agent_tier,omitempty"`
	Entries   []PackagedEntry `json:"entries"`
}

Block groups recalled entries by scope.

type CacheStableHeader

type CacheStableHeader struct {
	Text        string `json:"text"`
	ContentHash string `json:"content_hash"`
}

CacheStableHeader identifies the prompt-cache-stable header for a recall package.

type Candidate

type Candidate struct {
	WorkspaceID       string            `json:"workspace_id,omitempty"`
	Scope             Scope             `json:"scope"`
	AgentName         string            `json:"agent_name,omitempty"`
	AgentTier         AgentTier         `json:"agent_tier,omitempty"`
	Origin            Origin            `json:"origin"`
	Content           string            `json:"content"`
	Frontmatter       Header            `json:"frontmatter"`
	TrustedRawContent string            `json:"-"`
	Entity            string            `json:"entity,omitempty"`
	Attribute         string            `json:"attribute,omitempty"`
	Metadata          map[string]string `json:"metadata,omitempty"`
	SubmittedAt       time.Time         `json:"submitted_at"`
}

Candidate carries one fact proposed for the curated layer.

type Controller

type Controller interface {
	Decide(ctx context.Context, candidate Candidate) (Decision, error)
}

Controller decides how candidates mutate the curated memory layer.

type Decision

type Decision struct {
	ID              string         `json:"id"`
	CandidateHash   string         `json:"candidate_hash"`
	IdempotencyKey  string         `json:"idempotency_key"`
	Op              Op             `json:"op"`
	Targets         []string       `json:"targets,omitempty"`
	TargetFilename  string         `json:"target_filename"`
	Frontmatter     Header         `json:"frontmatter"`
	PostContent     string         `json:"post_content,omitempty"`
	PostContentHash string         `json:"post_content_hash,omitempty"`
	PriorContent    string         `json:"prior_content,omitempty"`
	Confidence      float32        `json:"confidence"`
	Source          DecisionSource `json:"source"`
	RuleTrace       []RuleHit      `json:"rule_trace,omitempty"`
	LLMTrace        *LLMCall       `json:"llm_trace,omitempty"`
	Reason          string         `json:"reason,omitempty"`
	PromptVersion   string         `json:"prompt_version,omitempty"`
	DecidedAt       time.Time      `json:"decided_at"`
}

Decision carries enough material to deterministically replay a file mutation.

type DecisionSource

type DecisionSource string

DecisionSource identifies whether a decision came from rules or an LLM tiebreaker.

const (
	SourceRule DecisionSource = "rule"
	SourceLLM  DecisionSource = "llm"
)

func (DecisionSource) Normalize

func (s DecisionSource) Normalize() DecisionSource

Normalize returns the normalized representation of the decision source.

func (DecisionSource) Validate

func (s DecisionSource) Validate() error

Validate reports whether the decision source belongs to the closed taxonomy.

type Extractor

type Extractor interface {
	Extract(ctx context.Context, turn TurnRecord) ([]Candidate, error)
	Drain(ctx context.Context) error
}

Extractor produces memory candidates from transcript turns.

type Header

type Header struct {
	Filename    string      `json:"filename"              yaml:"-"`
	FilePath    string      `json:"-"                     yaml:"-"`
	ModTime     time.Time   `json:"mod_time"              yaml:"-"`
	Name        string      `json:"name"                  yaml:"name"`
	Description string      `json:"description,omitempty" yaml:"description,omitempty"`
	Type        Type        `json:"type"                  yaml:"type"`
	Scope       Scope       `json:"scope,omitempty"       yaml:"scope,omitempty"`
	AgentName   string      `json:"agent_name,omitempty"  yaml:"agent,omitempty"`
	AgentTier   AgentTier   `json:"agent_tier,omitempty"  yaml:"agent_tier,omitempty"`
	Provenance  *Provenance `json:"provenance,omitempty"  yaml:"provenance,omitempty"`
}

Header contains validated metadata parsed from a memory file frontmatter.

func (*Header) Normalize

func (h *Header) Normalize()

Normalize trims and normalizes the parsed memory header metadata in place.

func (*Header) Validate

func (h *Header) Validate() error

Validate reports whether the parsed memory header is complete and valid.

type HealthStats

type HealthStats struct {
	IndexedFiles    int        `json:"indexed_files"`
	OrphanedFiles   int        `json:"orphaned_files"`
	LastReindex     *time.Time `json:"last_reindex"`
	OperationCount  int        `json:"operation_count"`
	LastOperationAt *time.Time `json:"last_operation_at"`
}

HealthStats summarizes derived-catalog state for operator surfaces.

type LLMCall

type LLMCall struct {
	Model         string        `json:"model"`
	PromptVersion string        `json:"prompt_version"`
	Latency       time.Duration `json:"latency"`
	RawResponse   string        `json:"raw_response,omitempty"`
	Error         string        `json:"error,omitempty"`
}

LLMCall records bounded metadata for an LLM tiebreaker call.

type MemoryProvider

type MemoryProvider interface {
	Initialize(ctx context.Context, init ProviderInit) error
	SystemPromptBlock(ctx context.Context, req SnapshotRequest) (SnapshotResult, error)
	Recall(ctx context.Context, req RecallRequest) (RecallResult, error)
	Prefetch(ctx context.Context, req PrefetchRequest) error
	SyncTurn(ctx context.Context, rec TurnRecord) error
	OnSessionEnd(ctx context.Context, rec SessionEndRecord) error
	OnSessionSwitch(ctx context.Context, rec SessionSwitchRecord) error
	OnPreCompress(ctx context.Context, req PreCompressRequest) (PreCompressHint, error)
	OnMemoryWrite(ctx context.Context, rec WriteRecord) error
	Shutdown(ctx context.Context) error
}

MemoryProvider is the lifecycle interface for pluggable memory backends.

type Op

type Op uint8

Op identifies a write-controller decision.

const (
	OpNoop Op = iota
	OpAdd
	OpUpdate
	OpDelete
	OpReject
)

func (Op) MarshalJSON

func (o Op) MarshalJSON() ([]byte, error)

MarshalJSON serializes Op as its canonical string value.

func (Op) Normalize

func (o Op) Normalize() Op

Normalize returns the canonical operation value.

func (Op) String

func (o Op) String() string

String returns the canonical JSON/DB value for the operation.

func (*Op) UnmarshalJSON

func (o *Op) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes Op from its canonical string value.

func (Op) Validate

func (o Op) Validate() error

Validate reports whether the operation belongs to the closed taxonomy.

type Operation

type Operation string

Operation identifies a durable memory operation surfaced in operator history.

const (
	OperationWrite   Operation = "memory.write"
	OperationDelete  Operation = "memory.delete"
	OperationSearch  Operation = "memory.search"
	OperationReindex Operation = "memory.reindex"
)

func (Operation) Normalize

func (o Operation) Normalize() Operation

Normalize returns the normalized operation string.

type OperationHistoryQuery

type OperationHistoryQuery struct {
	Scope     Scope
	Workspace string
	Operation Operation
	Since     time.Time
	Limit     int
}

OperationHistoryQuery filters durable memory operation history.

type OperationRecord

type OperationRecord struct {
	ID        string    `json:"id"`
	Operation Operation `json:"operation"`
	Scope     Scope     `json:"scope,omitempty"`
	Workspace string    `json:"workspace,omitempty"`
	Filename  string    `json:"filename,omitempty"`
	AgentName string    `json:"agent_name,omitempty"`
	Summary   string    `json:"summary,omitempty"`
	Timestamp time.Time `json:"timestamp"`
}

OperationRecord is one redacted durable memory operation history row.

type Origin

type Origin string

Origin identifies the surface that submitted a memory candidate.

const (
	OriginCLI       Origin = "cli"
	OriginHTTP      Origin = "http"
	OriginUDS       Origin = "uds"
	OriginTool      Origin = "tool"
	OriginExtractor Origin = "extractor"
	OriginDreaming  Origin = "dreaming"
	OriginFile      Origin = "file"
	OriginProvider  Origin = "provider"
)

func (Origin) Normalize

func (o Origin) Normalize() Origin

Normalize returns the normalized representation of the origin.

func (Origin) Validate

func (o Origin) Validate() error

Validate reports whether the origin belongs to the closed taxonomy.

type Packaged

type Packaged struct {
	Blocks []Block           `json:"blocks"`
	Header CacheStableHeader `json:"header"`
}

Packaged is the prompt-ready output of a recall query.

type PackagedEntry

type PackagedEntry struct {
	ID              string    `json:"id"`
	Filename        string    `json:"filename,omitempty"`
	Title           string    `json:"title"`
	Type            Type      `json:"type,omitempty"`
	WorkspaceID     string    `json:"workspace_id,omitempty"`
	Body            string    `json:"body"`
	ModTime         time.Time `json:"mod_time"`
	AgeDays         int       `json:"age_days"`
	StalenessBanner string    `json:"staleness_banner,omitempty"`
	WhyRecalled     []string  `json:"why_recalled,omitempty"`
}

PackagedEntry is one prompt-ready recalled memory entry.

type PreCompressHint

type PreCompressHint struct {
	Markdown string   `json:"markdown,omitempty"`
	Notes    []string `json:"notes,omitempty"`
}

PreCompressHint lets providers return memory guidance before compaction.

type PreCompressRequest

type PreCompressRequest struct {
	WorkspaceID string             `json:"workspace_id,omitempty"`
	SessionID   string             `json:"session_id"`
	Snapshot    TranscriptSnapshot `json:"snapshot"`
}

PreCompressRequest lets providers prepare before transcript compaction.

type PrefetchRequest

type PrefetchRequest struct {
	WorkspaceID string `json:"workspace_id,omitempty"`
	SessionID   string `json:"session_id"`
	AgentName   string `json:"agent_name,omitempty"`
	QueryText   string `json:"query_text,omitempty"`
}

PrefetchRequest lets providers warm data before a turn.

type Provenance

type Provenance struct {
	SourceSessionIDs []string  `json:"source_session_ids,omitempty" yaml:"source_sessions,omitempty"`
	SourceActor      Origin    `json:"source_actor"                 yaml:"source_actor"`
	Confidence       string    `json:"confidence,omitempty"         yaml:"confidence,omitempty"`
	SupersededBy     string    `json:"superseded_by,omitempty"      yaml:"superseded_by,omitempty"`
	CreatedAt        time.Time `json:"created_at"                   yaml:"created_at"`
	UpdatedAt        time.Time `json:"updated_at"                   yaml:"updated_at"`
}

Provenance records how a curated memory entry was created or superseded.

func (*Provenance) Normalize

func (p *Provenance) Normalize()

Normalize trims and normalizes provenance metadata in place.

func (*Provenance) Validate

func (p *Provenance) Validate() error

Validate reports whether provenance metadata is complete and valid.

type ProviderInit

type ProviderInit struct {
	WorkspaceID   string         `json:"workspace_id,omitempty"`
	WorkspaceRoot string         `json:"workspace_root,omitempty"`
	Config        map[string]any `json:"config,omitempty"`
	Logger        *slog.Logger   `json:"-"`
}

ProviderInit configures a memory provider for one workspace.

type Query

type Query struct {
	WorkspaceID string `json:"workspace_id,omitempty"`
	AgentName   string `json:"agent_name,omitempty"`
	QueryText   string `json:"query_text"`
	ContextHint string `json:"context_hint,omitempty"`
}

Query describes one recall query.

type RecallOptions

type RecallOptions struct {
	TopK                   int      `json:"top_k,omitempty"`
	RawCandidates          int      `json:"raw_candidates,omitempty"`
	IncludeAlreadySurfaced bool     `json:"include_already_surfaced,omitempty"`
	IncludeSystem          bool     `json:"include_system,omitempty"`
	AlreadySurfaced        []string `json:"already_surfaced,omitempty"`
	AllowTrivialQuery      bool     `json:"allow_trivial_query,omitempty"`
}

RecallOptions controls deterministic recall packaging.

type RecallRequest

type RecallRequest struct {
	Query
	Options RecallOptions `json:"options"`
}

RecallRequest asks a provider to recall memory.

type RecallResult

type RecallResult struct {
	Packaged
}

RecallResult wraps provider recall output.

type Recaller

type Recaller interface {
	Recall(ctx context.Context, query Query, opts RecallOptions) (Packaged, error)
}

Recaller retrieves prompt-ready memory for a query.

type ReindexOptions

type ReindexOptions struct {
	Scope     Scope
	Workspace string
}

ReindexOptions controls which scopes are rebuilt into the derived catalog.

type ReindexResult

type ReindexResult struct {
	IndexedFiles int       `json:"indexed_files"`
	Scope        Scope     `json:"scope,omitempty"`
	Workspace    string    `json:"workspace,omitempty"`
	CompletedAt  time.Time `json:"completed_at"`
}

ReindexResult reports the outcome of a catalog rebuild.

type RuleHit

type RuleHit struct {
	Name    string `json:"name"`
	Passed  bool   `json:"passed"`
	Reason  string `json:"reason,omitempty"`
	Target  string `json:"target,omitempty"`
	Details string `json:"details,omitempty"`
}

RuleHit records one deterministic rule that contributed to a write decision.

type Scope

type Scope string

Scope identifies the owner layer a memory entry belongs to.

const (
	ScopeGlobal    Scope = "global"
	ScopeWorkspace Scope = "workspace"
	ScopeAgent     Scope = "agent"
)

func DefaultScopeForType

func DefaultScopeForType(t Type) (Scope, error)

DefaultScopeForType resolves the default persistence scope for a memory type.

func (Scope) Normalize

func (s Scope) Normalize() Scope

Normalize returns the normalized representation of the scope.

func (Scope) Validate

func (s Scope) Validate() error

Validate reports whether the scope belongs to the closed taxonomy.

type SearchOptions

type SearchOptions struct {
	Scope     Scope
	Workspace string
	Limit     int
}

SearchOptions controls catalog-backed or fallback memory search behavior.

type SearchResult

type SearchResult struct {
	Filename    string    `json:"filename"`
	Scope       Scope     `json:"scope"`
	Workspace   string    `json:"workspace,omitempty"`
	Type        Type      `json:"type"`
	Name        string    `json:"name"`
	Description string    `json:"description,omitempty"`
	Score       float64   `json:"score"`
	Snippet     string    `json:"snippet,omitempty"`
	ModTime     time.Time `json:"mod_time"`
}

SearchResult is one ranked memory search hit.

type SessionEndRecord

type SessionEndRecord struct {
	WorkspaceID string             `json:"workspace_id,omitempty"`
	SessionID   string             `json:"session_id"`
	AgentName   string             `json:"agent_name,omitempty"`
	EndedAt     time.Time          `json:"ended_at"`
	Snapshot    TranscriptSnapshot `json:"snapshot"`
}

SessionEndRecord describes a completed session for provider synchronization.

type SessionSwitchRecord

type SessionSwitchRecord struct {
	WorkspaceID string    `json:"workspace_id,omitempty"`
	FromSession string    `json:"from_session"`
	ToSession   string    `json:"to_session"`
	SwitchedAt  time.Time `json:"switched_at"`
}

SessionSwitchRecord describes a session lineage handoff.

type SnapshotRequest

type SnapshotRequest struct {
	Scope         Scope     `json:"scope"`
	AgentName     string    `json:"agent_name,omitempty"`
	AgentTier     AgentTier `json:"agent_tier,omitempty"`
	WorkspaceID   string    `json:"workspace_id,omitempty"`
	WorkspaceRoot string    `json:"workspace_root,omitempty"`
}

SnapshotRequest asks a provider for a frozen prompt snapshot.

type SnapshotResult

type SnapshotResult struct {
	Markdown string `json:"markdown"`
	AgeMs    int64  `json:"age_ms"`
}

SnapshotResult is provider-supplied markdown for prompt injection.

type TranscriptMessage

type TranscriptMessage struct {
	Sequence int64     `json:"sequence"`
	Role     string    `json:"role"`
	Content  string    `json:"content"`
	At       time.Time `json:"at"`
}

TranscriptMessage is one compact message in an extractor snapshot.

type TranscriptSnapshot

type TranscriptSnapshot struct {
	Messages []TranscriptMessage `json:"messages"`
}

TranscriptSnapshot contains bounded transcript material for extraction.

type Trigger

type Trigger string

Trigger identifies why an extractor run was requested.

const (
	TriggerPostMessage     Trigger = "post_message"
	TriggerCompactionFlush Trigger = "compaction_flush"
)

func (Trigger) Normalize

func (t Trigger) Normalize() Trigger

Normalize returns the normalized representation of the extractor trigger.

func (Trigger) Validate

func (t Trigger) Validate() error

Validate reports whether the trigger belongs to the closed taxonomy.

type TurnRecord

type TurnRecord struct {
	SessionID       string             `json:"session_id"`
	RootSessionID   string             `json:"root_session_id"`
	ParentSessionID string             `json:"parent_session_id,omitempty"`
	AgentID         string             `json:"agent_id"`
	ActorKind       string             `json:"actor_kind"`
	WorkspaceID     string             `json:"workspace_id,omitempty"`
	SinceMessageSeq int64              `json:"since_message_seq"`
	UntilMessageSeq int64              `json:"until_message_seq"`
	Snapshot        TranscriptSnapshot `json:"snapshot"`
	Trigger         Trigger            `json:"trigger"`
}

TurnRecord describes the message range inspected by the extractor.

type Type

type Type string

Type identifies the closed persistent-memory taxonomy.

const (
	TypeUser      Type = "user"
	TypeFeedback  Type = "feedback"
	TypeProject   Type = "project"
	TypeReference Type = "reference"
)

func (Type) Normalize

func (t Type) Normalize() Type

Normalize returns the normalized representation of the memory type.

func (Type) Validate

func (t Type) Validate() error

Validate reports whether the memory type belongs to the closed taxonomy.

type WriteRecord

type WriteRecord struct {
	Decision  Decision  `json:"decision"`
	Candidate Candidate `json:"candidate"`
}

WriteRecord is emitted to providers after a controller decision.