Skip to main content
Retrieval methods surface memory records that are relevant to the caller’s current task. Every retrieval call requires a TrustContext that controls which records are visible based on sensitivity level and scope.

​
Trust-aware retrieval

Membrane enforces graduated access control on every read. A record is returned only when both conditions are met:
  1. The record’s sensitivity level is at or below the trust context’s max_sensitivity.
  2. If the trust context specifies scopes, the record’s scope must match one of them (unscoped records are visible to all callers).
Records that are exactly one sensitivity level above the caller’s maximum are returned in redacted form — metadata only, with the payload removed. Records two or more levels above are not returned at all.
Record sensitivityCaller maxResult
lowmediumFull record
mediummediumFull record
highmediumRedacted (metadata only)
hypermediumNot returned

​
Retrieval layer order

When no memory_types filter is specified, Retrieve queries all five types in the following canonical order: 
working → semantic → competence → plan_graph → episodic
Results are sorted by salience descending. When competence or plan_graph records are present, the selector runs applicability scoring before the final sort.

​
Retrieve

Performs layered retrieval across one or more memory types with trust filtering and salience ranking.

​
Request fields

​
task_descriptor
string
Describes the current task. Used as the query for applicability scoring of competence and plan_graph records. When a Postgres + pgvector backend with embeddings is configured, this field drives semantic similarity search.
​
trust
object
required
Trust context that gates which records are visible.
​
memory_types
string[]
Restrict retrieval to specific memory types: episodic, working, semantic, competence, plan_graph. When omitted, all types are queried in layer order.
​
min_salience
number
Minimum salience threshold. Records with salience below this value are excluded. Must be non-negative and finite.
​
limit
number
Maximum number of records to return. 0 means no limit. Maximum is 10 000.

​
Response fields

​
records
bytes[]
Array of JSON-encoded MemoryRecord objects, sorted by salience descending.
​
selection
bytes
JSON-encoded SelectionResult when competence or plan_graph candidates were scored by the selector. May be null when no competence or plan_graph records exist in the result set.

​
Examples

resp, err := m.Retrieve(ctx, &retrieval.RetrieveRequest{
    TaskDescriptor: "fix build error",
    Trust: &retrieval.TrustContext{
        MaxSensitivity: schema.SensitivityMedium,
        Authenticated:  true,
    },
    MemoryTypes: []schema.MemoryType{
        schema.MemoryTypeCompetence,
        schema.MemoryTypeSemantic,
    },
})

for _, r := range resp.Records {
    fmt.Printf("Found: %s (type=%s, confidence=%.2f)\n", r.ID, r.Type, r.Confidence)
}

​
Trust-filtered retrieval example

This pattern retrieves only records that the caller is authorised to see, with scope restriction to a single project:
Go — scoped, authenticated retrieval
resp, err := m.Retrieve(ctx, &retrieval.RetrieveRequest{
    TaskDescriptor: "plan a safe migration",
    Trust: retrieval.NewTrustContext(
        schema.SensitivityMedium,
        true,           // authenticated
        "planner-agent",
        []string{"project-acme"},
    ),
    MemoryTypes: []schema.MemoryType{
        schema.MemoryTypeSemantic,
        schema.MemoryTypeCompetence,
        schema.MemoryTypeWorking,
    },
    Limit: 12,
})
For LLM integration, map each returned record to a JSON string and include it in the system or user prompt. Records carry their type, confidence, salience, and structured payload, giving the model typed context rather than raw text.

​
RetrieveByID

Fetches a single record by its UUID. The same trust rules apply: the record is returned only if its sensitivity is within the caller’s trust context.

​
Request fields

​
id
string
required
UUID of the record to retrieve.
​
trust
object
required
Trust context that gates access.

​
Response fields

​
record
bytes
JSON-encoded MemoryRecord. Returns NOT_FOUND if the ID does not exist, or PERMISSION_DENIED if the trust context denies access.

​
Example

rec, err := m.RetrieveByID(ctx, recordID, &retrieval.TrustContext{
    MaxSensitivity: schema.SensitivityMedium,
    Authenticated:  true,
})
if err != nil {
    log.Printf("record not found or access denied: %v", err)
    return
}
fmt.Printf("Record type: %s, salience: %.2f\n", rec.Type, rec.Salience)

Build docs developers (and LLMs) love

Get started for freeTalk to us