memory

type CallerBlockAdmittedPayload ¶ added in v1.25.0

type CallerBlockAdmittedPayload struct {
	events.SafeSealed `json:"-"`

	// Bytes is the size of the admitted document as it arrived on the
	// wire. It is the only caller-influenced value on the payload.
	Bytes int `json:"bytes"`
	// Tier is the prompt tier the content was admitted into — the
	// runtime-owned wrapper name, always the read-only external-memory
	// tier.
	Tier string `json:"tier"`
	// Key is the fixed runtime-owned map key the content was composed
	// under within that tier.
	Key string `json:"key"`
}

CallerBlockAdmittedPayload is the audit payload for EventTypeMemoryCallerBlockAdmitted. SafePayload BY CONSTRUCTION, and the construction is the point: the only caller-derived quantity on it is a byte COUNT. `Tier` and `Key` are runtime-owned constants, not caller input — the caller names no key.

No fragment of the admitted content appears here, and none may ever be added: the payload is caller-controlled bytes that would require redaction, and the audit trail records THAT an admission happened and how large it was, never what it said (CLAUDE.md §7 rules 6-7).

type ConfigSnapshot ¶

type ConfigSnapshot struct {
	Driver             string
	DSN                string
	MigrationMode      sqlmigrate.Mode
	Strategy           Strategy
	BudgetTokens       int
	RecoveryBacklogMax int
	RecentTurns        int
	Retrieval          RetrievalMode
	RetrievalTopK      int
}

ConfigSnapshot is the strict subset of `config.MemoryConfig` the memory package consumes. Keeping a snapshot decouples drivers from the config package's type evolution. Callers (typically `cmd/harbor/main.go`'s bootstrap or a test wiring helper) translate `config.MemoryConfig` → `ConfigSnapshot` at the seam.

`DSN` is consumed by the SQLite + Postgres drivers; the InMem driver ignores it. Validation of "DSN required for persistent drivers" lives at the config layer (`validateMemory` in `internal/config/validate.go`) and at the driver constructor itself — fail-loudly twice so a misconfiguration surfaces early.

`RecoveryBacklogMax` is consumed by the `rolling_summary` strategy executor only; other strategies ignore the field. Default (zero) → strategy.DefaultRecoveryBacklogMax. `Retrieval` opts in to a retrieval mode layered ON TOP of the strategy (the default keeps strategy-shaped retrieval only; `RetrievalSemantic` additionally serves `SearchTurns`). `RetrievalTopK` caps semantic results when the caller passes no limit; zero → `DefaultSemanticTopK`. Both are ignored by the default mode.

`RecentTurns` is the verbatim recent-window size for the `rolling_summary` strategy. Zero selects the strategy default (`strategy.FullZoneTurns`); positive values override it. Ignored by `none` and `truncation`.

func SnapshotFromConfig(cfg config.MemoryConfig) ConfigSnapshot

type ConversationTurn ¶

type ConversationTurn struct {
	UserMessage         string
	AssistantResponse   string
	TrajectoryDigest    *TrajectoryDigest
	ArtifactsShown      map[string]any
	ArtifactsHiddenRefs []string
	Timestamp           time.Time
}

ConversationTurn is one turn of a memory-tracked conversation. Producers (the planner runtime) hand turns to `AddTurn`.

`ArtifactsShown` / `ArtifactsHiddenRefs` carry the model-visible / model-hidden artifact references for this turn so memory's downstream injection logic can prune or include them per the configured strategy. Snapshot/Restore round-trips both fields through the Snapshot bytes but applies no strategy logic.

type Deps ¶

type Deps struct {
	State      state.StateStore
	Bus        events.EventBus
	Summarizer Summarizer
	Embedder   Embedder
}

Deps carries the runtime dependencies a memory driver needs.

The `State` field is mandatory (typed wrapper writes opaque bytes through the generic surface). The `Bus` field is mandatory so identity-rejection emits land on the audit pipeline. Drivers MUST NOT accept missing deps silently; the registry rejects an `Open` call whose Deps omits either with a wrapped error.

The `Summarizer` field is the injectable LLM-edge callable the `rolling_summary` strategy consumes. It is OPTIONAL — required only when `cfg.Strategy == StrategyRollingSummary`, ignored by `none` / `truncation`. The registry routes it into the driver factory, which threads it into the strategy executor. A `rolling_summary` config without a `Summarizer` fails loudly at `Open` (mirroring `strategy.New`'s rejection) — never a stub fallback (AGENTS.md §13). Existing callers that construct `Deps{State, Bus}` keep compiling: the zero value is nil, valid for the non-summarising strategies. The `Embedder` field is the injectable text→vector callable the `semantic` retrieval mode consumes. It is OPTIONAL — required only when `cfg.Retrieval == RetrievalSemantic`, ignored otherwise. A semantic config without an Embedder fails loudly at `Open` (mirroring the Summarizer rule) — never a stub fallback (AGENTS.md §13). Existing callers that construct `Deps{State, Bus}` keep compiling: the zero value is nil, valid for the default retrieval mode.

type Embedder ¶ added in v1.4.0

type Embedder interface {
	Embed(ctx context.Context, texts []string) ([][]float32, error)
}

Embedder is the injectable text→vector callable the semantic retrieval mode consumes — the same consumer-side-interface shape as `Summarizer`. The canonical implementation is constructed via the embeddings factory (`internal/embeddings`); any `embeddings.Embedder` satisfies this interface.

Concurrent-reuse contract: one `Embedder` instance is safe to share across N concurrent goroutines. Implementers MUST honour `ctx.Done()`.

type Factory ¶

type Factory func(cfg ConfigSnapshot, deps Deps) (MemoryStore, error)

Factory builds a `MemoryStore` from a `ConfigSnapshot` + `Deps`. Drivers expose one `Factory` each via `init()` → `Register`.

type Health ¶

type Health string

Health enumerates the memory subsystem health states.

only produces `HealthHealthy`. A later phase will drive the full FSM (`healthy → retry → degraded → recovering → healthy`) for `rolling_summary` failures.

const (
	// HealthHealthy — operating normally.
	HealthHealthy Health = "healthy"
	// HealthRetry — last summarisation attempt failed; will retry
	// next opportunity. Reserved for a later phase.
	HealthRetry Health = "retry"
	// HealthDegraded — retry budget exhausted; falling back to
	// truncation semantics and queueing recovery. Reserved for
	HealthDegraded Health = "degraded"
	// HealthRecovering — recovery loop is running; will return to
	// healthy on success. Reserved for a later phase.
	HealthRecovering Health = "recovering"
)

type HealthChangedPayload ¶

type HealthChangedPayload struct {
	events.SafeSealed
	PriorHealth Health
	NewHealth   Health
	Reason      string
}

HealthChangedPayload reports a `Health` FSM transition. SafePayload by construction — `PriorHealth` + `NewHealth` are bounded enumerable strings; `Reason` is a short static string indicating the transition cause ("summarizer_failed", "retries_exhausted", "recovery_loop_drained", etc.). No caller-controlled bytes survive on the payload.

Subscribers MAY admin-scope-filter to fan-in cross-tenant health transitions for fleet-level alerting.

type LLMContextPatch ¶

type LLMContextPatch struct {
	Strategy    Strategy
	Summary     string
	RecentTurns []ConversationTurn
	Tokens      int
}

LLMContextPatch is the output `GetLLMContext` returns: the patch a planner runtime applies to its LLM call.

Strategy=none returns an empty patch; later strategies return a rolling summary text, ordered recent turns, and a token estimate the planner can compare against its context-window budget.

type MemoryIdentityRejectedPayload ¶

type MemoryIdentityRejectedPayload struct {
	events.SafeSealed
	Operation string
	Reason    string
}

MemoryIdentityRejectedPayload reports a missing-identity rejection. SafePayload by construction — both fields are bounded enumerable strings (the operation name + a static reason); no caller-controlled bytes survive on the payload.

`Operation` is the rejected method name ("AddTurn", "GetLLMContext", etc.). `Reason` is a short static string indicating which component was missing ("tenant_id empty" / "user_id empty" / "session_id empty" / "tenant_id and user_id empty", etc.).

The Event's `Identity` field carries whatever the caller supplied (zeroed or partial); the bus's `ValidateEvent` would normally reject empty-triple events, so the bus publisher substitutes the missing components with a `"<missing>"` sentinel so the rejection event itself is bus-publishable. Subscribers MAY admin-scope- filter to fan-in cross-tenant rejections.

type MemoryMutationPayload ¶ added in v1.3.0

type MemoryMutationPayload struct {
	events.SafeSealed
	Operation string
	Key       string
}

MemoryMutationPayload is the audit payload for the `memory.item_put` / `memory.item_deleted` events. SafePayload by construction: `Operation` is a bounded enumerable string ("put" / "delete"); `Key` is the deterministic content-addressed turn key (a sha256 prefix), never operator-supplied bytes. The record value text is NEVER carried here — it is caller-controlled and would require redaction; the audit trail records THAT a mutation happened, by key, not its bytes.

type MemoryStore ¶

type MemoryStore interface {
	// AddTurn appends a conversation turn to the memory tracked
	// for `id`. Strategy=none is a no-op (returns nil); other
	// strategies will apply their shape logic.
	AddTurn(ctx context.Context, id identity.Quadruple, turn ConversationTurn) error

	// GetLLMContext returns the patch a planner runtime applies to
	// its LLM call. Strategy=none returns the zero value of
	// `LLMContextPatch`.
	GetLLMContext(ctx context.Context, id identity.Quadruple) (LLMContextPatch, error)

	// EstimateTokens returns the token-estimate for the memory
	// payload `GetLLMContext` would inject right now. Strategy=
	// none returns 0.
	EstimateTokens(ctx context.Context, id identity.Quadruple) (int, error)

	// Flush drops every in-flight turn and resets the memory for
	// `id` to a clean state. Strategy=none is a no-op.
	Flush(ctx context.Context, id identity.Quadruple) error

	// Health reports the current health state for `id`'s memory.
	// Strategy=none always reports `HealthHealthy`.
	Health(ctx context.Context, id identity.Quadruple) (Health, error)

	// Snapshot exports a portable snapshot of `id`'s memory state.
	// Strategy=none returns an empty `Snapshot{Strategy: StrategyNone}`.
	Snapshot(ctx context.Context, id identity.Quadruple) (Snapshot, error)

	// SearchTurns returns up to `limit` stored turns ranked by
	// embedding similarity to `query`, identity-scoped — retrieval
	// never crosses the `(tenant, user, session)` boundary. Only
	// the semantic retrieval mode serves it; every other mode fails
	// loudly with `ErrSemanticDisabled` (never an empty success).
	// `limit <= 0` falls back to the configured `RetrievalTopK`
	// (default `DefaultSemanticTopK`). An empty query is an error.
	SearchTurns(ctx context.Context, id identity.Quadruple, query string, limit int) ([]ScoredTurn, error)

	// Restore imports a previously-captured `Snapshot`. The
	// Snapshot's Strategy MUST match the driver's configured
	// Strategy; mismatched strategies (e.g. restoring a
	// `truncation` snapshot into a `none` store) returns
	// `ErrInvalidSnapshot`. Strategy=none accepts only empty
	// snapshots; non-empty Bytes returns `ErrInvalidSnapshot`.
	Restore(ctx context.Context, id identity.Quadruple, snap Snapshot) error

	// Close releases driver resources. Idempotent. After Close,
	// every method returns `ErrStoreClosed`.
	Close(ctx context.Context) error
}

MemoryStore is Harbor's mandatory memory interface. A single surface; every V1 driver (inmem here, sqlite + postgres at Postgres) implements every method. No `Supports*` ceremony per AGENTS.md §4.4.

Identity-mandatory contract:

• Every method validates the identity `Quadruple` at the boundary. Empty tenant / user / session returns wrapped `ErrIdentityRequired` AND emits one `memory.identity_rejected` event on the bus. Empty `RunID` is accepted (memory is session-scoped).

Concurrent-reuse contract:

• One instance is safe to share across N concurrent goroutines. Mutable state is internally synchronised; per- call state lives in `ctx` and the supplied `Quadruple`, never on the driver.

func From(ctx context.Context) (MemoryStore, bool)

func MustFrom(ctx context.Context) MemoryStore

func Open(_ context.Context, cfg ConfigSnapshot, deps Deps) (MemoryStore, error)

func OpenDriver(name string, cfg ConfigSnapshot, deps Deps) (MemoryStore, error)

type OverflowPolicy ¶

type OverflowPolicy string

OverflowPolicy is the buffer-overflow action a `truncation`-style strategy applies when the recent-window buffer's token total exceeds the configured `BudgetTokens`. Harbor ships only `OverflowDropOldest`. The original trio `truncate_oldest | truncate_summary | error` was narrowed to a single safe default; the `error` policy is a silent- degradation footgun and `truncate_summary` conflates strategies).

const (
	// OverflowDropOldest evicts oldest turns until the buffer's
	// token estimate fits within the budget. The only shipped
	// policy.
	OverflowDropOldest OverflowPolicy = "drop_oldest"
)

type RecallSettings ¶ added in v1.4.0

type RecallSettings struct {
	// Enabled is true when memory.retrieval is "semantic". When false,
	// SearchTurns is never called and the prompt is unchanged.
	Enabled bool
	// TopK is the maximum number of recalled turns to inject. 0 falls
	// back to the memory subsystem default (DefaultSemanticTopK = 5).
	TopK int
	// MinScore is the cosine-similarity floor. Turns scoring below
	// this value are not injected. Valid range [-1, 1]; default 0.0.
	MinScore float64
}

RecallSettings carries the run-loop recall parameters the FetchMemoryBlocks helper reads. It is separate from ConfigSnapshot so a headless caller that builds its own RunSpec can supply recall settings without constructing a full config.MemoryConfig.

The zero value is valid: Enabled=false means semantic recall is off and SearchTurns is never called.

func RecallFromConfig(cfg config.MemoryConfig) RecallSettings

type Record ¶

type Record struct {
	Strategy Strategy           `json:"strategy"`
	Turns    []ConversationTurn `json:"turns,omitempty"`
	// Summary is the rolling-summary text the `rolling_summary` strategy
	// folds compacted turns into. Added in so a
	// Snapshot → drop-turn → Restore read-modify-write (the `memory.delete`
	// mutation) round-trips the summary LOSSLESSLY rather than dropping it.
	// The json tag matches the strategy's persisted `memoryStateRecord`
	// (`internal/memory/strategy`), so decoding a real snapshot into this
	// envelope and re-marshalling preserves every field. `omitempty` keeps
	// it byte-compatible with pre-108n records that never wrote a summary.
	Summary string `json:"summary,omitempty"`
}

Record is the JSON envelope every driver persists as the opaque `Snapshot.Bytes` payload. The shape is exported so tests + later driver implementations share a single source of truth (wire envelope centralised in the `memory` package for cross-driver byte-stable Snapshot/Restore).

only writes empty records (Strategy=none has no mutations). A later phase will populate `Turns` for the truncation + rolling_summary strategies. The struct's JSON tags pin the wire format and MUST NOT change after An earlier phase merged — additive fields are fine (later strategies will append fields), but renaming an existing field would break cross-driver round-trip.

type RecoveryDroppedPayload ¶

type RecoveryDroppedPayload struct {
	events.SafeSealed
	Reason string
}

RecoveryDroppedPayload reports a recovery-backlog overflow drop. SafePayload by construction — `Reason` is a short static string ("backlog_overflow"); no caller-controlled bytes.

type RetrievalMode ¶ added in v1.4.0

type RetrievalMode string

RetrievalMode declares the opt-in retrieval shape layered on top of the strategy. The mode COMPOSES with the configured `Strategy` — `rolling_summary` keeps its summary + recent-turn patch unchanged; a semantic mode additionally serves similarity search over embedded turns via `SearchTurns`.

const (
	// RetrievalDefault — the zero value. Retrieval is shaped by the
	// strategy alone; `SearchTurns` fails loudly with
	// `ErrSemanticDisabled`.
	RetrievalDefault RetrievalMode = ""
	// RetrievalSemantic — turns are embedded at `AddTurn` (vectors
	// persist alongside the memory records through the same
	// StateStore floor, identity-scoped) and `SearchTurns` ranks by
	// cosine similarity. Requires `Deps.Embedder` — no stub
	// fallback.
	RetrievalSemantic RetrievalMode = "semantic"
)

type ScoredTurn ¶ added in v1.4.0

type ScoredTurn struct {
	Turn  ConversationTurn
	Score float64
}

ScoredTurn is one `SearchTurns` result: a stored conversation turn plus its similarity score (cosine, in [-1, 1], higher is closer).

type Snapshot ¶

type Snapshot struct {
	Strategy Strategy
	Bytes    []byte
}

Snapshot is the export shape for `Snapshot` / `Restore`. The Strategy field round-trips so a `Restore` against a driver configured for a different Strategy fails loudly.

`Bytes` is opaque to callers; only a driver of the same Strategy can `Restore` them. Crossing driver boundaries (e.g. inmem snapshot → sqlite restore) is safe because the bytes are JSON-serialised internal records, not driver-private structures.

func (s Snapshot) IsEmpty() bool

type Strategy ¶

type Strategy string

Strategy declares the memory shape the store applies.

Harbor ships `StrategyNone` operational. `StrategyTruncation` and `StrategyRollingSummary` are declared so operators can stage their config today; the registry's `Open` rejects them with `ErrStrategyNotImplemented` until a later phase lands.

const (
	// StrategyNone is the no-op memory shape. AddTurn is a no-op;
	// GetLLMContext returns an empty patch. Operationally the
	// "memory disabled" mode.
	StrategyNone Strategy = "none"
	// StrategyTruncation keeps a recent-turn window with budget
	// enforcement. Reserved for a later phase.
	StrategyTruncation Strategy = "truncation"
	// StrategyRollingSummary keeps a recent-turn window plus a
	// background-summarised long-term context. Reserved for a later phase.
	StrategyRollingSummary Strategy = "rolling_summary"
)

type SummarizeRequest ¶

type SummarizeRequest struct {
	PreviousSummary string
	Turns           []ConversationTurn
}

SummarizeRequest carries the summariser inputs. `PreviousSummary` is the prior rolling summary (empty on the first turn); `Turns` is the batch of recently-evicted turns to fold into the summary.

type SummarizeResponse ¶

type SummarizeResponse struct {
	Summary string
}

SummarizeResponse carries the summariser output.

type Summarizer ¶

type Summarizer interface {
	Summarize(ctx context.Context, id identity.Quadruple, req SummarizeRequest) (SummarizeResponse, error)
}

Summarizer is the injectable callable the `rolling_summary` strategy consumes. The LLM-backed implementation lands +; Harbor ships only the interface and a test-grade stub (`EchoSummarizer`, exported from `internal/memory/strategy`).

The interface intentionally mirrors the "input `{previous_summary, turns}`, output `{summary: string}`" with a Go-idiomatic `(ctx, identity, req)` shape so the LLM-client integration phase doesn't have to invent a fresh shape.

Concurrent-reuse contract: one `Summarizer` instance is safe to share across N concurrent goroutines. Implementers MUST honour `ctx.Done()`; the executor cancels in-flight summaries on `Close`.

type TrajectoryDigest ¶

type TrajectoryDigest struct {
	ToolsInvoked        []string
	ObservationsSummary string
	ReasoningSummary    string
	ArtifactsRefs       []string
}

TrajectoryDigest is the compact planner-side trace snapshot the memory subsystem MAY persist alongside the turn. Harbor does not ingest it (Strategy=none); the type ships now so the strategy layer and downstream planner phases share one definition.