memory

type Access ¶ added in v1.32.0

type Access struct {
	// contains filtered or unexported fields
}

Access binds driver operations to the cumulative owner and holds no session state.

func NewAccess(cfg ConfigSnapshot, deps Deps) *Access

func (a *Access) Delete(ctx context.Context, id identity.Quadruple, key string) (int, error)

func (a *Access) Inspect(ctx context.Context, id identity.Quadruple) (Inspection, error)

func (a *Access) Put(ctx context.Context, id identity.Quadruple, turn ConversationTurn) (string, error)

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

RecentTurns bounds detailed recent execution evidence. Zero selects twenty.

func SnapshotFromConfig(cfg config.MemoryConfig) ConfigSnapshot

type ConversationTurn ¶

type ConversationTurn struct {
	UserMessage       string
	AssistantResponse string
}

ConversationTurn is an administrator-supplied conversational note. Runtime turns are recorded through the cumulative execution owner, not Put.

type Deps ¶

type Deps struct {
	State state.StateStore
	Bus   events.EventBus
	// Redactor and RetentionTTL are the same execution-memory dependencies
	// supplied by runtime composition. Put refuses a missing redactor.
	Redactor     audit.Redactor
	RetentionTTL time.Duration
}

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.

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 Inspection ¶ added in v1.32.0

type Inspection struct {
	Strategy        Strategy
	Items           []Item
	Summary         string
	RecentTurns     int
	EstimatedTokens int
	Health          Health
}

Inspection is a bounded read of committed execution memory, never another transcript.

type Item ¶ added in v1.32.0

type Item = sessionmemory.Item

Item is an immutable, source-keyed projection of committed session memory.

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 {
	// Inspect reads the authoritative committed memory projection. It exposes
	// neither active journals nor a second persisted transcript.
	Inspect(ctx context.Context, id identity.Quadruple) (Inspection, error)
	// Put appends an operator note and returns its actual committed key.
	Put(ctx context.Context, id identity.Quadruple, turn ConversationTurn) (string, error)
	// Delete atomically removes the named item and fences derived context.
	Delete(ctx context.Context, id identity.Quadruple, key string) (int, 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 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 Strategy ¶

type Strategy string

Strategy declares the memory shape the store applies.

const (
	// StrategyNone explicitly disables session memory.
	StrategyNone Strategy = "none"
	// StrategyRollingSummary retains cumulative context and recent execution detail.
	StrategyRollingSummary Strategy = "rolling_summary"
)