contract

package
v0.0.5 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 29, 2026 License: MIT Imports: 7 Imported by: 0

Documentation

Overview

Package contract defines the shared Memory v2 data contract.

Index

Constants

This section is empty.

Variables

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

ErrNotImplemented lets optional provider methods request the local fallback.

Functions

This section is empty.

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 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.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.