retrieval

Import path: github.com/BennettSchwartz/membrane/pkg/retrieval

The retrieval package implements trust-gated retrieval, graph expansion, redaction, and competence/plan selection. The top-level Membrane facade exposes RetrieveGraph and RetrieveByID; the package also keeps lower-level retrieval primitives used internally by graph retrieval.

Note

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
func NewServiceWithVectorRanker(store storage.Store, selector *Selector, embedding EmbeddingService, ranker VectorRanker) *Service

membrane.New chooses the right constructor based on Config. With Postgres + pgvector and embeddings configured, the service uses hybrid vector and salience ranking.

---

RetrieveGraph

func (svc *Service) RetrieveGraph(ctx context.Context, req *RetrieveGraphRequest) (*RetrieveGraphResponse, error)

Retrieves ranked root memories for a task descriptor, then expands a bounded graph neighborhood from each root.

RetrieveGraphRequest

TaskDescriptorstring

Natural-language description of the current task.

Trust*TrustContextrequired

Trust context that gates all returned records.

MemoryTypes[]schema.MemoryType

Optional filter. Valid values are episodic, working, semantic, competence, plan_graph, and entity.

MinSaliencefloat64

Minimum salience threshold.

RootLimitint

Maximum number of root records. Service default is 10 when zero.

NodeLimitint

Maximum total graph nodes. Service default is 25 when zero.

EdgeLimitint

Maximum graph edges. Service default is 100 when zero.

MaxHopsint

Graph expansion depth. 0 returns roots only.

RetrieveGraphResponse

Nodes[]GraphNode

Returned records annotated with Root and Hop.

Edges[]schema.GraphEdge

Graph edges between returned records.

RootIDs[]string

IDs of ranked root records.

Selection*SelectionResult

Selector metadata when competence or plan graph candidates were scored.

trust := retrieval.NewTrustContext(
    schema.SensitivityMedium,
    true,
    "user:alice",
    []string{"project:auth"},
)

resp, err := m.RetrieveGraph(ctx, &retrieval.RetrieveGraphRequest{
    TaskDescriptor: "debug auth retries",
    Trust:          trust,
    MemoryTypes: []schema.MemoryType{
        schema.MemoryTypeEntity,
        schema.MemoryTypeSemantic,
        schema.MemoryTypeCompetence,
        schema.MemoryTypeEpisodic,
    },
    RootLimit: 8,
    NodeLimit: 20,
    EdgeLimit: 80,
    MaxHops:   1,
})
if err != nil {
    log.Fatal(err)
}
for _, node := range resp.Nodes {
    fmt.Println(node.Record.ID, node.Record.Type, node.Root, node.Hop)
}

---

Retrieve

func (svc *Service) Retrieve(ctx context.Context, req *RetrieveRequest) (*RetrieveResponse, error)

Lower-level layered retrieval used by graph retrieval. It returns a flat list of records and optional selector metadata.

RetrieveRequest

TaskDescriptorstring

Natural-language task descriptor. When embeddings are configured, this is encoded into a query vector.

QueryEmbedding[]float32

Optional precomputed query embedding.

Trust*TrustContextrequired

Trust context for filtering and redaction.

MemoryTypes[]schema.MemoryType

Restricts retrieval to the specified memory types. Empty means all types in canonical layer order.

MinSaliencefloat64

Records below this salience are excluded.

Limitint

Maximum number of records. 0 means no limit.

RetrieveResponse

Records[]*schema.MemoryRecord

Filtered, sorted, and limited records.

Selection*SelectionResult

Non-nil when competence or plan graph candidates were evaluated.

---

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 trust. Returns storage.ErrNotFound when missing and ErrAccessDenied when trust denies access.

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

Access is allowed when:

• The record sensitivity is at or below MaxSensitivity.
• The record scope is empty, Scopes is empty, or the record scope appears in Scopes.

func (tc *TrustContext) Allows(record *schema.MemoryRecord) bool
func (tc *TrustContext) AllowsRedacted(record *schema.MemoryRecord) bool

AllowsRedacted returns true when the record is exactly one sensitivity level above the caller's maximum. Redaction strips payload, provenance, relations, and audit log.

---

Selector

type Selector struct { ... }

func NewSelector(confidenceThreshold float64) *Selector
func NewSelectorWithEmbedding(confidenceThreshold float64, embedding EmbeddingProvider) *Selector
func (s *Selector) Select(ctx context.Context, candidates []*schema.MemoryRecord, queryEmbedding []float32) *SelectionResult

The selector ranks competence and plan graph candidates using:

1. Applicability, based on record confidence or embedding similarity.
2. Observed success rate from competence or plan metrics.
3. Recency, based on last reinforcement time.

SelectionResult

Selected[]*schema.MemoryRecord

Candidates ranked by composite score.

Confidencefloat64

Selection confidence in [0, 1].

NeedsMorebool

True when confidence is below the selector threshold.

Scoresmap[string]float64

Composite score per candidate record ID.

---

Layer Order

When no memory type filter is supplied, retrieval uses this canonical order:

working -> entity -> semantic -> competence -> plan_graph -> episodic