Documentation
¶
Overview ¶
Package retrieval implements the layered memory retrieval service as specified in RFC 15.8 and RFC 15A.11.
Index ¶
- Variables
- func FilterBySalience(records []*schema.MemoryRecord, minSalience float64) []*schema.MemoryRecord
- func FilterBySensitivity(records []*schema.MemoryRecord, maxSensitivity schema.Sensitivity) []*schema.MemoryRecord
- func FilterByTrust(records []*schema.MemoryRecord, trust *TrustContext) []*schema.MemoryRecord
- func Redact(record *schema.MemoryRecord) *schema.MemoryRecord
- func SensitivityLevel(s schema.Sensitivity) int
- func SortBySalience(records []*schema.MemoryRecord)
- type RetrieveRequest
- type RetrieveResponse
- type SelectionResult
- type Selector
- type Service
- func (svc *Service) Retrieve(ctx context.Context, req *RetrieveRequest) (*RetrieveResponse, error)
- func (svc *Service) RetrieveByID(ctx context.Context, id string, trust *TrustContext) (*schema.MemoryRecord, error)
- func (svc *Service) RetrieveByType(ctx context.Context, memType schema.MemoryType, trust *TrustContext) ([]*schema.MemoryRecord, error)
- type TrustContext
Constants ¶
This section is empty.
Variables ¶
var ( // ErrAccessDenied is returned when a trust context denies access to a record. ErrAccessDenied = errors.New("access denied by trust context") // ErrNilTrust is returned when a nil trust context is provided. ErrNilTrust = errors.New("trust context is required") )
Common retrieval errors.
Functions ¶
func FilterBySalience ¶
func FilterBySalience(records []*schema.MemoryRecord, minSalience float64) []*schema.MemoryRecord
FilterBySalience returns only records whose salience is at or above the given minimum threshold.
func FilterBySensitivity ¶
func FilterBySensitivity(records []*schema.MemoryRecord, maxSensitivity schema.Sensitivity) []*schema.MemoryRecord
FilterBySensitivity returns only records whose sensitivity level is at or below the given maximum sensitivity.
func FilterByTrust ¶
func FilterByTrust(records []*schema.MemoryRecord, trust *TrustContext) []*schema.MemoryRecord
FilterByTrust returns records that the given TrustContext allows. Records at exactly one sensitivity level above the threshold are returned in redacted form (metadata only, no sensitive content).
func Redact ¶
func Redact(record *schema.MemoryRecord) *schema.MemoryRecord
Redact creates a redacted copy of a MemoryRecord, preserving metadata while removing sensitive content. This implements graduated exposure per RFC Section 13.
A redacted record retains:
- ID, Type, Sensitivity, Confidence, Salience, CreatedAt, UpdatedAt, Scope, Tags
And clears:
- Payload (set to nil)
- Provenance (empty)
- AuditLog (empty)
This gives metadata visibility without exposing sensitive content.
func SensitivityLevel ¶
func SensitivityLevel(s schema.Sensitivity) int
SensitivityLevel returns the numeric level for a given sensitivity. Unknown sensitivity values return -1.
func SortBySalience ¶
func SortBySalience(records []*schema.MemoryRecord)
SortBySalience sorts records by salience in descending order (highest first).
Types ¶
type RetrieveRequest ¶
type RetrieveRequest struct {
// TaskDescriptor describes the current task for contextual retrieval.
TaskDescriptor string
// Trust is the trust context that gates what records can be returned.
Trust *TrustContext
// MemoryTypes optionally restricts retrieval to specific memory types.
// If empty, all types are queried in layered order.
MemoryTypes []schema.MemoryType
// MinSalience filters out records below this salience threshold.
MinSalience float64
// Limit caps the total number of returned records. 0 means no limit.
Limit int
}
RetrieveRequest specifies parameters for a layered retrieval query.
type RetrieveResponse ¶
type RetrieveResponse struct {
// Records contains the filtered, sorted, and limited results.
Records []*schema.MemoryRecord
// Selection is non-nil when competence or plan_graph candidates were
// evaluated through the multi-solution selector (RFC 15A.11).
Selection *SelectionResult
}
RetrieveResponse contains the results of a layered retrieval query.
type SelectionResult ¶
type SelectionResult struct {
// Selected contains the ranked candidates in descending score order.
Selected []*schema.MemoryRecord
// Confidence is the selection confidence in [0, 1].
// Computed as the score gap between the best and second-best candidate,
// normalized by the best score.
Confidence float64
// NeedsMore is true when confidence falls below the selector's threshold,
// indicating that additional information or user disambiguation is needed.
NeedsMore bool
}
SelectionResult holds the outcome of multi-solution selection per RFC 15A.11. When multiple competence records or plan graphs match a query, the selector ranks them and reports confidence in the selection.
type Selector ¶
type Selector struct {
// contains filtered or unexported fields
}
Selector performs multi-solution selection for competence and plan_graph records using three signals: applicability, observed success rate, and recency of reinforcement.
func NewSelector ¶
NewSelector creates a Selector with the given confidence threshold. If confidence falls below the threshold, SelectionResult.NeedsMore is set to true.
func (*Selector) Select ¶
func (s *Selector) Select(candidates []*schema.MemoryRecord) *SelectionResult
Select ranks candidate records and returns a SelectionResult. Candidates are scored using three equally-weighted signals:
- Applicability conditions - trigger/constraint match (approximated by confidence field).
- Observed success rate - from PerformanceStats (success_count / total).
- Recency of reinforcement - more recently reinforced records score higher.
If fewer than one candidate is provided, the result has zero confidence.
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service is the main retrieval service implementing layered memory retrieval per RFC 15.8.
func NewService ¶
NewService creates a new retrieval Service backed by the given store and selector.
func (*Service) Retrieve ¶
func (svc *Service) Retrieve(ctx context.Context, req *RetrieveRequest) (*RetrieveResponse, error)
Retrieve performs layered retrieval as specified in RFC 15.8. It queries the store for each memory type layer in order, applies trust and salience filtering, runs competence/plan_graph results through the selector, sorts by salience descending, and applies the limit.
func (*Service) RetrieveByID ¶
func (svc *Service) RetrieveByID(ctx context.Context, id string, trust *TrustContext) (*schema.MemoryRecord, error)
RetrieveByID fetches a single record by ID and checks it against the trust context. Returns storage.ErrNotFound if the record does not exist, or ErrAccessDenied if the trust context does not allow access.
func (*Service) RetrieveByType ¶
func (svc *Service) RetrieveByType(ctx context.Context, memType schema.MemoryType, trust *TrustContext) ([]*schema.MemoryRecord, error)
RetrieveByType fetches all records of a given type that pass the trust check.
type TrustContext ¶
type TrustContext struct {
// MaxSensitivity is the maximum sensitivity level the requester is allowed to access.
MaxSensitivity schema.Sensitivity
// Authenticated indicates whether the requester has been authenticated.
Authenticated bool
// ActorID identifies who is making the retrieval request.
ActorID string
// Scopes lists the scopes the requester is allowed to access.
// An empty slice means all scopes are allowed.
Scopes []string
}
TrustContext gates retrieval based on the requester's trust attributes. Records that exceed the trust context's sensitivity or fall outside the allowed scopes are filtered out during retrieval.
func NewTrustContext ¶
func NewTrustContext(maxSensitivity schema.Sensitivity, authenticated bool, actorID string, scopes []string) *TrustContext
NewTrustContext creates a new TrustContext with the given parameters.
func (*TrustContext) Allows ¶
func (tc *TrustContext) Allows(record *schema.MemoryRecord) bool
Allows checks whether the given record is accessible under this trust context. A record is allowed if:
- Its sensitivity level does not exceed the trust context's MaxSensitivity.
- Its scope matches one of the allowed scopes (or the trust context has no scope restrictions).
func (*TrustContext) AllowsRedacted ¶
func (tc *TrustContext) AllowsRedacted(record *schema.MemoryRecord) bool
AllowsRedacted returns true if the record's sensitivity is exactly one level above the trust context's maximum, allowing a redacted view. This implements graduated exposure per RFC Section 13: "sensitive records may be summarized or withheld." Records at this level are visible as metadata but with sensitive content removed.
Source Files