Skip to main content
Import path: github.com/GustyCube/membrane/pkg/retrieval The retrieval package implements layered memory retrieval per RFC 15.8. Records are queried in canonical layer order (working → semantic → competence → plan_graph → episodic), filtered by trust context and salience, optionally ranked by a multi-solution selector, and returned sorted by salience descending.
All retrieval operations require a non-nil TrustContext. Passing nil returns ErrNilTrust.

​
Service

type Service struct { ... }

func NewService(store storage.Store, selector *Selector) *Service
func NewServiceWithEmbedding(store storage.Store, selector *Selector, embedding EmbeddingService) *Service
Use NewServiceWithEmbedding to enable semantic similarity scoring at retrieval time. Membrane.New wires the correct constructor automatically based on the Config.

​
EmbeddingService interface

type EmbeddingService interface {
    EmbedQuery(ctx context.Context, taskDescriptor string) ([]float32, error)
}

​
Retrieve

func (svc *Service) Retrieve(ctx context.Context, req *RetrieveRequest) (*RetrieveResponse, error)
Performs layered retrieval. Queries each memory type in canonical order, applies trust and salience filters, runs competence and plan_graph candidates through the Selector, then sorts and limits the result set.

​
RetrieveRequest

​
TaskDescriptor
string
Natural-language description of the current task. When an embedding service is configured, this is encoded into a query vector used for applicability scoring in the Selector.
​
Trust
*TrustContext
required
Trust context that gates which records can be returned. Must not be nil.
​
MemoryTypes
[]schema.MemoryType
Restricts retrieval to the specified memory types. When empty, all types are queried in canonical layer order.
​
MinSalience
float64
Records with Salience below this threshold are excluded. 0 disables the filter.
​
Limit
int
Maximum number of records to return. 0 means no limit.

​
RetrieveResponse

​
Records
[]*schema.MemoryRecord
Filtered, sorted, and limited result set.
​
Selection
*SelectionResult
Non-nil when competence or plan_graph candidates were evaluated through the multi-solution selector. nil if no such candidates were found.
trust := retrieval.NewTrustContext(
    schema.SensitivityMedium,
    true,
    "user:alice",
    []string{"project:myapp"},
)

resp, err := m.Retrieve(ctx, &retrieval.RetrieveRequest{
    TaskDescriptor: "deploy the application to production",
    Trust:          trust,
    MinSalience:    0.3,
    Limit:          20,
})
if err != nil {
    log.Fatal(err)
}
for _, rec := range resp.Records {
    fmt.Println(rec.ID, rec.Type, rec.Salience)
}

​
RetrieveByID

func (svc *Service) RetrieveByID(ctx context.Context, id string, trust *TrustContext) (*schema.MemoryRecord, error)
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 denies access.
​
id
string
required
Unique ID of the record to fetch.
​
trust
*TrustContext
required
Trust context for access control.
rec, err := m.RetrieveByID(ctx, "550e8400-e29b-41d4-a716-446655440000", trust)
if errors.Is(err, storage.ErrNotFound) {
    // record does not exist
} else if errors.Is(err, retrieval.ErrAccessDenied) {
    // insufficient trust
}

​
TrustContext

type TrustContext struct {
    MaxSensitivity schema.Sensitivity
    Authenticated  bool
    ActorID        string
    Scopes         []string
}

func NewTrustContext(maxSensitivity schema.Sensitivity, authenticated bool, actorID string, scopes []string) *TrustContext
Gates retrieval based on the requester’s trust attributes. A record is accessible when:
  • Its Sensitivity level does not exceed MaxSensitivity.
  • Its Scope matches one of the listed Scopes (or the record has no scope, or Scopes is empty).
​
MaxSensitivity
schema.Sensitivity
required
Maximum sensitivity level the requester is allowed to access.
​
Authenticated
bool
Whether the requester has been authenticated.
​
ActorID
string
Identifies who is making the retrieval request.
​
Scopes
[]string
Scopes the requester is allowed to access. An empty slice grants access to all scopes.

​
Methods

func (tc *TrustContext) Allows(record *schema.MemoryRecord) bool
func (tc *TrustContext) AllowsRedacted(record *schema.MemoryRecord) bool
AllowsRedacted returns true when the record’s sensitivity is exactly one level above MaxSensitivity, enabling a redacted metadata view per RFC Section 13.

​
Selector

type Selector struct { ... }

func NewSelector(confidenceThreshold float64) *Selector
func NewSelectorWithEmbedding(confidenceThreshold float64, embedding EmbeddingProvider) *Selector
Ranks competence and plan_graph candidates using three equally-weighted signals:
  1. Applicability — the record’s Confidence field (or embedding similarity when an EmbeddingProvider is configured).
  2. Observed success rate — derived from PerformanceStats (competence) or PlanMetrics.FailureRate (plan graph). Defaults to 0.5 when no data is available.
  3. Recency — exponential decay with a 30-day half-life from Lifecycle.LastReinforcedAt.
func (s *Selector) Select(ctx context.Context, candidates []*schema.MemoryRecord, queryEmbedding []float32) *SelectionResult

​
EmbeddingProvider interface

type EmbeddingProvider interface {
    Similarity(ctx context.Context, recordID string, query []float32) (float64, bool)
}

​
SelectionResult

​
Selected
[]*schema.MemoryRecord
Candidates ranked in descending composite score order.
​
Confidence
float64
Selection confidence in [0, 1]. Computed as the normalised score gap between the best and second-best candidate.
​
NeedsMore
bool
true when Confidence falls below the selector’s threshold, indicating disambiguation is needed.
​
Scores
map[string]float64
Composite score for each candidate record ID.

​
RetrieveByType

func (svc *Service) RetrieveByType(ctx context.Context, memType schema.MemoryType, trust *TrustContext) ([]*schema.MemoryRecord, error)
Fetches all records of the given memory type that pass the trust context check, sorted by salience descending.
​
memType
schema.MemoryType
required
The memory type to query: episodic, working, semantic, competence, or plan_graph.
​
trust
*TrustContext
required
Trust context for access control. Must not be nil.
records, err := svc.RetrieveByType(ctx, schema.MemoryTypeCompetence, trust)
if err != nil {
    log.Fatal(err)
}
for _, rec := range records {
    fmt.Println(rec.ID, rec.Confidence)
}
RetrieveByType is a lower-level convenience method on Service. The top-level Membrane facade does not expose it directly — use Retrieve with MemoryTypes set for equivalent behaviour through the public API.

​
Errors

SymbolDescription
ErrAccessDeniedReturned by RetrieveByID when the trust context denies access to the record.
ErrNilTrustReturned by any operation when a nil TrustContext is provided.

Build docs developers (and LLMs) love

Get started for freeTalk to us