Part of archie-core-1786637490069-11-e245c170 (memory engine contract and owning registry), under epic archie-core-1786637499161 (pluggable memory engine). Stands up internal/domain/memory as a conforming engine family per the strict plugin engine rule, mirroring internal/domain/curator's split exactly as that issue's notes specify: - contract.go: MemoryEngine (Lifecycle + Store + identity + Bind), with Store carrying the real domain operations the epic requires -- Write/Query/List/Forget -- not just Name/Version. Store is split out from MemoryEngine so the interface stays under golangci-lint's interfacebloat threshold the same way curator's embedded Lifecycle does: an embedded interface counts as one slot, not its expanded method count. - registrar.go: narrow typed host access (EventSink, Clock). No capability-gated fields yet -- unlike curator's Tools/Skills, no memory-specific host service exists to gate on today, so Registry.Bind passes the host straight through rather than filtering. - registry.go: Register/Get/Names/Start/Health/Stop with the same duplicate/nil/panic/failure-isolation guarantees as curator's registry, ctx-bounded Stop, reverse-order shutdown. This is the contract only -- no engine implements it yet, and internal/memory's existing ad-hoc MemoryProvider/Manager (pre-migration) is untouched, per the issue's explicit "do not extend in place" note.
157 lines
5.6 KiB
Go
157 lines
5.6 KiB
Go
// Package memory is the memory engine family: a pluggable backend for
|
|
// durable observations about a session or identity, so an external memory
|
|
// service (Honcho, or a future alternative) can be bolted on without
|
|
// touching the agent loop. See epic archie-core-1786637499161-356-e424e40d.
|
|
//
|
|
// The family follows the strict plugin engine rule: a typed contract
|
|
// (MemoryEngine) with real domain operations (write, query, list, forget —
|
|
// not just Name/Version), an owning registry (Registry) with
|
|
// start/health/stop and shutdown ordering, and narrow typed host access
|
|
// (Registrar) — an engine never receives the daemon or an untyped hook map.
|
|
//
|
|
// This package defines the contract only. internal/memory's existing
|
|
// MemoryProvider and Manager predate the domain migration and are the
|
|
// current runtime path; they are not extended in place (see
|
|
// archie-core-1786637490069-11-e245c170's notes) and are superseded by this
|
|
// family as engines land against it.
|
|
package memory
|
|
|
|
import (
|
|
"context"
|
|
"errors"
|
|
"time"
|
|
)
|
|
|
|
// HealthStatus is an engine's point-in-time health.
|
|
type HealthStatus string
|
|
|
|
const (
|
|
HealthHealthy HealthStatus = "healthy"
|
|
HealthDegraded HealthStatus = "degraded"
|
|
HealthUnhealthy HealthStatus = "unhealthy"
|
|
)
|
|
|
|
// Health is a point-in-time engine health report.
|
|
type Health struct {
|
|
Status HealthStatus
|
|
Message string
|
|
}
|
|
|
|
// Manifest is an engine's declared shape. RequiresNetwork marks an engine
|
|
// that calls an external service, so a caller can size timeouts and
|
|
// failure-isolation expectations accordingly: a non-default engine's
|
|
// failure must degrade to a reported error, never take down a turn.
|
|
type Manifest struct {
|
|
RequiresNetwork bool
|
|
}
|
|
|
|
// Validate checks the declared shape. It is called by the registry at
|
|
// registration; present for symmetry with the curator family and as the
|
|
// seam for future required fields, even though no field is required yet.
|
|
func (m Manifest) Validate() error { return nil }
|
|
|
|
// Lifecycle is the start/health/stop contract every engine implements. The
|
|
// registry drives it with shutdown ordering and failure isolation; an
|
|
// engine's Health must never panic the daemon.
|
|
type Lifecycle interface {
|
|
Start(ctx context.Context) error
|
|
Health(ctx context.Context) Health
|
|
Stop(ctx context.Context) error
|
|
}
|
|
|
|
// Store is the real domain operations every memory backend implements —
|
|
// what the epic requires beyond identity metadata. Split out from
|
|
// MemoryEngine so the two concerns (storage vs. identity/lifecycle) stay
|
|
// separately named and independently testable.
|
|
type Store interface {
|
|
// Write records one observation and returns the stored Record,
|
|
// including the identifier Forget later needs.
|
|
Write(ctx context.Context, obs Observation) (Record, error)
|
|
// Query returns records relevant to q, most relevant or most recent
|
|
// first — ordering is engine-defined and not part of this contract.
|
|
Query(ctx context.Context, q Query) ([]Record, error)
|
|
// List returns every record for identity, for inspection and
|
|
// deletion flows rather than relevance-ranked recall.
|
|
List(ctx context.Context, identity string) ([]Record, error)
|
|
// Forget permanently removes one record. Forgetting an id that does
|
|
// not exist is not an error: the end state (id absent) already holds.
|
|
Forget(ctx context.Context, id string) error
|
|
}
|
|
|
|
// MemoryEngine is the typed contract every memory backend implements.
|
|
// Name/Version are identity, Manifest declares the shape, Store carries
|
|
// the real domain operations, Bind receives narrow host access, and
|
|
// Lifecycle carries start/health/stop.
|
|
type MemoryEngine interface {
|
|
Lifecycle
|
|
Store
|
|
Name() string
|
|
Version() string
|
|
Manifest() Manifest
|
|
// Bind attaches the engine's narrow host access. The registry calls
|
|
// Bind exactly once, at registration.
|
|
Bind(host Registrar)
|
|
}
|
|
|
|
// Observation is one fact to remember, submitted for writing.
|
|
type Observation struct {
|
|
// Identity is whose memory this is about (a session id, a user id —
|
|
// engine-defined, but always required so Query/List/Forget have a
|
|
// scope to operate within).
|
|
Identity string
|
|
// Kind is a freeform category ("preference", "fact", "correction").
|
|
Kind string
|
|
// Content is the observation itself.
|
|
Content string
|
|
// At is when the observation was made. Zero means the engine should
|
|
// stamp it with the current time.
|
|
At time.Time
|
|
// Metadata carries engine-agnostic key/value context alongside the
|
|
// observation (e.g. source, confidence).
|
|
Metadata map[string]string
|
|
}
|
|
|
|
// Validate checks the fields every engine needs regardless of backend:
|
|
// Identity scopes every other operation, and Content is the whole point
|
|
// of writing.
|
|
func (o Observation) Validate() error {
|
|
if o.Identity == "" {
|
|
return errors.New("memory observation: identity must not be empty")
|
|
}
|
|
if o.Content == "" {
|
|
return errors.New("memory observation: content must not be empty")
|
|
}
|
|
return nil
|
|
}
|
|
|
|
// Query asks an engine to recall observations relevant to Text within
|
|
// Identity's scope.
|
|
type Query struct {
|
|
Identity string
|
|
Text string
|
|
// Limit bounds the number of records returned. Zero lets the engine
|
|
// choose a default; there is no way to request "unlimited" — List
|
|
// exists for that.
|
|
Limit int
|
|
}
|
|
|
|
// Validate checks the field every engine needs to scope a query: Identity.
|
|
// Text may be empty (some engines support a scope-only recall), so it is
|
|
// not required here.
|
|
func (q Query) Validate() error {
|
|
if q.Identity == "" {
|
|
return errors.New("memory query: identity must not be empty")
|
|
}
|
|
return nil
|
|
}
|
|
|
|
// Record is one stored observation as returned by Write, Query, or List.
|
|
type Record struct {
|
|
ID string
|
|
Identity string
|
|
Kind string
|
|
Content string
|
|
At time.Time
|
|
Metadata map[string]string
|
|
}
|