Documentation
¶
Index ¶
- type ConsolidateMode
- type ListInput
- type Metrics
- type Option
- func WithClock(now func() time.Time) Option
- func WithConsolidateMinScore(minScore float64) Option
- func WithConsolidateMode(m ConsolidateMode) Option
- func WithConsolidator(c llm.Consolidator) Option
- func WithDistiller(d llm.Distiller) Option
- func WithIDGenerator(gen func() string) Option
- func WithMetrics(m Metrics) Option
- func WithPromoteMinAccess(n int) Option
- func WithQueryPrefix(p string) Option
- func WithRecallPool(factor, floor int) Option
- func WithScoreFusion(alpha float64) Option
- func WithShortTermCap(cap int) Option
- func WithSyncReinforce() Option
- func WithWriteDedup(minScore float64) Option
- type RecallInput
- type RememberInput
- type Service
- func (s *Service) Forget(ctx context.Context, namespace, id string) error
- func (s *Service) Fsck(ctx context.Context) (maintenance.Report, error)
- func (s *Service) Get(ctx context.Context, namespace, id string) (*memory.Memory, error)
- func (s *Service) List(ctx context.Context, in ListInput) ([]*memory.Memory, error)
- func (s *Service) Namespaces(ctx context.Context) ([]string, error)
- func (s *Service) Promote(ctx context.Context) (int, error)
- func (s *Service) Recall(ctx context.Context, in RecallInput) ([]store.Scored, error)
- func (s *Service) Remember(ctx context.Context, in RememberInput) (*memory.Memory, error)
- func (s *Service) RunPromoter(ctx context.Context, interval time.Duration)
- func (s *Service) StartConsolidator(ctx context.Context)
- func (s *Service) Stats(ctx context.Context, namespace string) (Stats, error)
- type Stats
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ConsolidateMode ¶
type ConsolidateMode string
ConsolidateMode selects how the opt-in LLM consolidation pipeline runs.
const ( // ConsolidateAsync stores writes immediately and consolidates in the // background — writes never block on the LLM. The default. ConsolidateAsync ConsolidateMode = "async" // ConsolidateSync consolidates before returning, so a write reflects its // dedup/supersede outcome immediately (read-your-consolidated-writes). ConsolidateSync ConsolidateMode = "sync" // ConsolidateOff disables consolidation even when a consolidator is set. ConsolidateOff ConsolidateMode = "off" )
type ListInput ¶
type ListInput struct {
Namespace string
Tiers []memory.Tier
IncludeExpired bool
IncludeSuperseded bool
// Limit caps the result count; <= 0 returns all matches.
Limit int
}
ListInput selects a slice of a namespace's memories for browsing. The zero value (besides Namespace) lists all live memories, newest store order.
type Metrics ¶
type Metrics interface {
// ConsolidateResult records one consolidation outcome: one of
// "gated", "new", "update", "supersede", "noop", "error", "dropped".
ConsolidateResult(result string)
// ConsolidateQueueDepth reports the current async queue depth.
ConsolidateQueueDepth(depth int)
// RememberResult records the outcome of a Remember call: result is
// "ok"|"error" and tier is the memory's tier.
RememberResult(result, tier string)
// RecallResult records the outcome of a Recall call. result is
// "ok"|"error"; tierFilter is one of "all"|"working"|"episodic"|
// "semantic"|"procedural"|"mixed"; hitsBucket is a pre-bucketed
// count of returned memories: "0"|"1"|"2-5"|"6-20"|"21+".
RecallResult(result, tierFilter, hitsBucket string)
// ForgetResult records the outcome of a Forget call: "ok"|"not_found"|"error".
ForgetResult(result string)
// PromoteResult records one Promote batch: result is "ok"|"error";
// facts is the number of semantic facts written.
PromoteResult(result string, facts int)
// FsckResult records one fsck pass: "ok"|"error". Counters for the
// work done (purged, evicted, duplicate groups) are exposed separately
// via the store's maintenance metrics.
FsckResult(result string)
// OpDuration observes end-to-end latency for a public operation.
OpDuration(op string, d time.Duration)
}
Metrics receives service-level events for observability. Methods must be safe for concurrent use; a nil Metrics is replaced by a no-op.
type Option ¶
type Option func(*Service)
Option customizes a Service.
func WithConsolidateMinScore ¶
WithConsolidateMinScore sets the similarity gate: the LLM is only consulted when the nearest candidate scores at least minScore. 0 disables the gate.
func WithConsolidateMode ¶
func WithConsolidateMode(m ConsolidateMode) Option
WithConsolidateMode selects async (default), sync, or off.
func WithConsolidator ¶
func WithConsolidator(c llm.Consolidator) Option
WithConsolidator enables the opt-in LLM consolidation pipeline.
func WithDistiller ¶
WithDistiller enables episodic→semantic promotion via RunPromoter.
func WithIDGenerator ¶
WithIDGenerator overrides ID generation (tests).
func WithMetrics ¶
WithMetrics installs an observability sink for consolidation events.
func WithPromoteMinAccess ¶
WithPromoteMinAccess sets the minimum access_count for an episodic memory to be eligible for promotion.
func WithQueryPrefix ¶
WithQueryPrefix prepends an instruction to recall queries before embedding (e.g. the retrieval instruct expected by Qwen3-Embedding or bge models). Documents keep bare embeddings; the keyword leg keeps the raw query.
func WithRecallPool ¶
WithRecallPool overrides the per-leg candidate pool sizing (max(k*factor, floor)) for hybrid recall. Non-positive values keep the defaults. Used by the benchmark harness to sweep pool depth.
func WithScoreFusion ¶
WithScoreFusion sets the hybrid fusion weight: the vector leg by alpha and the keyword leg by 1-alpha (score fusion). alpha < 0 selects rank fusion (RRF). The package default is score fusion at DefaultFusionAlpha.
func WithShortTermCap ¶
WithShortTermCap bounds short-term memories per namespace, enforced by fsck.
func WithSyncReinforce ¶
func WithSyncReinforce() Option
WithSyncReinforce makes recall reinforcement run synchronously (tests).
func WithWriteDedup ¶
WithWriteDedup coalesces a fresh write into an existing same-tier memory when their vector similarity is at or above minScore, instead of storing a near-duplicate. It only acts when the LLM consolidation pipeline is not handling the write (no consolidator, a non-durable tier, or consolidation off), giving headless deployments basic corpus hygiene. 0 disables it.
type RecallInput ¶
type RecallInput struct {
Namespace string
Query string
Tiers []memory.Tier
Limit int
// IncludeExpired / IncludeSuperseded relax the default live-only filter.
IncludeExpired bool
IncludeSuperseded bool
}
RecallInput describes a hybrid recall query.
type RememberInput ¶
type RememberInput struct {
Namespace string
Content string
Tier memory.Tier
Summary string
Tags []string
Metadata map[string]any
Importance float64
// TTL overrides the tier default. A negative TTL means "never expire".
TTL *time.Duration
// ID upserts an existing memory when set; otherwise a new ID is generated.
ID string
}
RememberInput describes a memory to store. Only Namespace and Content are required; Tier defaults to working and TTL to the tier default.
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service wires storage and embeddings together. It is safe for concurrent use.
func (*Service) Fsck ¶
Fsck runs a consistency sweep: purge expired, enforce the short-term cap, and audit live memories for duplicate clusters.
func (*Service) List ¶
List returns memories in a namespace matching the filter, without embeddings. It backs the UI memory browser and the client-derived relationship graph.
func (*Service) Namespaces ¶
Namespaces returns the distinct namespaces holding memories, for the UI tenant switcher.
func (*Service) Promote ¶
Promote distills frequently-accessed, not-yet-promoted episodic memories in each namespace into durable semantic facts (written via Remember so they get the similarity gate and consolidation dedup), then stamps the sources so they aren't reprocessed. Returns the number of facts written. No-op without a distiller.
func (*Service) RunPromoter ¶
RunPromoter periodically distills frequently-accessed episodic memories into durable semantic facts until ctx is cancelled. It is a no-op without a distiller or a positive interval. Call once, typically in its own goroutine.
func (*Service) StartConsolidator ¶
StartConsolidator runs the background consolidation worker until ctx is cancelled, then drains queued jobs within a bounded timeout. It is a no-op unless the service was built with a consolidator in async mode. Call once, typically in its own goroutine.
type Stats ¶
type Stats struct {
Namespace string `json:"namespace"`
Total int `json:"total"` // live memories (excludes expired/superseded)
ByTier map[memory.Tier]int `json:"by_tier"` // live count per tier
Expired int `json:"expired"` // past-TTL, not yet swept
Superseded int `json:"superseded"` // contradiction-tombstoned
TotalAccesses int `json:"total_accesses"`
AvgImportance float64 `json:"avg_importance"`
LastWriteAt *time.Time `json:"last_write_at,omitempty"`
}
Stats summarizes a namespace for the UI dashboard. Counts are computed from a full listing, so callers should treat it as a curated-namespace overview, not a hot-path metric (Prometheus /metrics remains the source for operational counters).
Source Files