Documentation
¶
Overview ¶
Package strategy holds the memory-strategy executors: the algorithmic core that any `memory.MemoryStore` driver delegates to. The strategy is a behaviour mode of the driver, not a separate driver per AGENTS.md §4.4 — every memory driver hosts the same executor surface.
Harbor ships three executors:
- `none` (`noneExec`) — Strategy=none preserves the semantics: AddTurn is a no-op, GetLLMContext returns empty, all snapshot bytes round-trip through `state.StateStore`.
- `truncation` (`truncationExec`) — synchronous recent-window buffer with `OverflowDropOldest` enforcement at the configured `BudgetTokens` boundary.
- `rolling_summary` (`rollingSummaryExec`) — recent-window buffer + background-summarised long-term context. Health FSM `healthy → retry → degraded → recovering → healthy` with a bounded recovery backlog (`RecoveryBacklogMax`); failure paths emit `memory.health_changed` and `memory.recovery_dropped` events so degradation is observable, not silent.
Persistence: every successful mutation lands as a `state.StateStore` record at `Kind = "memory.state"` (typed wrapper). the SQLite + Postgres drivers will inherit the shape unchanged.
Identity-mandatory contract: every method validates the identity quadruple at the boundary. Drivers OWN the boundary validation + the `memory.identity_rejected` emit; executors trust the driver's pre-validation. The driver passes through validated identities and the executor focuses on the algorithmic core.
Concurrent-reuse contract: one executor is safe to share across N concurrent goroutines. Per-key state lives in mutex- guarded maps inside the executor; no per-call mutable state on the executor struct itself.
Index ¶
Constants ¶
const DefaultRecoveryBacklogMax = 16
DefaultRecoveryBacklogMax is the default recovery-backlog cap for the rolling-summary strategy when `Deps.RecoveryBacklogMax` is zero. Sized to absorb a short summariser outage (≈4 minutes at `defaultDegradedRetryEvery = 10s` × 16 retries) without unbounded memory growth.
const FullZoneTurns = 4
FullZoneTurns is the DEFAULT recent-window size before turns spill into the rolling-summary `pending` queue. Operators override it via `memory.recent_turns` (threaded to `Deps.RecentTurns`); this constant is the fallback used when that knob is unset.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Deps ¶
type Deps struct {
State state.StateStore
Bus events.EventBus
Summarizer memory.Summarizer
BudgetTokens int
RecoveryBacklogMax int
RecentTurns int
Embedder memory.Embedder
Retrieval memory.RetrievalMode
RetrievalTopK int
}
Deps carries the runtime dependencies an executor consumes.
`State` is the persistence floor — every executor writes typed records through it. Mandatory for every strategy including `none` (the wiring is exercised by the conformance suite).
`Bus` is the event bus the executor publishes lifecycle events on — `memory.identity_rejected` (driver-side; passed through here so executors can re-emit if needed), `memory.health_changed` (rolling-summary FSM transitions), `memory.recovery_dropped` (bounded-backlog overflow). Mandatory.
`Summarizer` is the injectable LLM-edge callable the rolling-summary strategy consumes. Mandatory for `StrategyRollingSummary`; ignored by other strategies. The LLM-backed implementation lands in later phases; Harbor ships a test-grade stub (`EchoSummarizer`).
`BudgetTokens` is the truncation / rolling-summary budget cap (per-key, applied as token estimates). Zero is honoured as "no budget" — appending is unbounded. Positive values enforce the `OverflowDropOldest` policy.
`RecoveryBacklogMax` is the bounded queue size for the rolling-summary recovery loop. Zero defaults to `DefaultRecoveryBacklogMax` (16).
`RecentTurns` is the verbatim recent-window size the rolling-summary strategy keeps before older turns spill into the summary. Zero selects the `FullZoneTurns` default; positive values override it. Ignored by the other strategies. `Embedder` / `Retrieval` / `RetrievalTopK` configure the opt-in semantic retrieval mode layered on top of the strategy executor. `Embedder` is mandatory when `Retrieval == RetrievalSemantic` and ignored otherwise; `RetrievalTopK` caps `SearchTurns` results when the caller passes no limit (zero → `memory.DefaultSemanticTopK`).
type EchoSummarizer ¶
type EchoSummarizer struct{}
EchoSummarizer is the test-grade `memory.Summarizer` stub Harbor ships. It concatenates the previous summary + the joined user/assistant turns into a deterministic string so tests can pin expected outputs without an LLM backend.
The real LLM-backed `Summarizer` lands in later phases in the `internal/llm` subsystem; tests in reach for `EchoSummarizer` because (a) it is fully deterministic, and (b) it never hits the network so the test suite stays hermetic.
Concurrent-reuse contract: no mutable state on the struct; safe to share across N goroutines.
func (EchoSummarizer) Summarize ¶
func (EchoSummarizer) Summarize(_ context.Context, _ identity.Quadruple, req memory.SummarizeRequest) (memory.SummarizeResponse, error)
Summarize implements `memory.Summarizer`.
type StrategyExecutor ¶
type StrategyExecutor interface {
AddTurn(ctx context.Context, id identity.Quadruple, turn memory.ConversationTurn) error
GetLLMContext(ctx context.Context, id identity.Quadruple) (memory.LLMContextPatch, error)
EstimateTokens(ctx context.Context, id identity.Quadruple) (int, error)
Flush(ctx context.Context, id identity.Quadruple) error
Health(ctx context.Context, id identity.Quadruple) (memory.Health, error)
Snapshot(ctx context.Context, id identity.Quadruple) (memory.Snapshot, error)
SearchTurns(ctx context.Context, id identity.Quadruple, query string, limit int) ([]memory.ScoredTurn, error)
Restore(ctx context.Context, id identity.Quadruple, snap memory.Snapshot) error
Close(ctx context.Context) error
}
func New ¶
func New(s memory.Strategy, deps Deps) (StrategyExecutor, error)
New constructs the strategy executor for the given strategy. Unknown strategies return wrapped `memory.ErrStrategyNotImplemented`.
Harbor routes:
StrategyNone → noneExec (no-op surface; preserves semantics) StrategyTruncation → truncationExec StrategyRollingSummary → rollingSummaryExec
A nil `Deps.State` or `Deps.Bus` returns a wrapped construction error. A nil `Deps.Summarizer` is rejected for `StrategyRollingSummary` and ignored for the others.
Source Files