Memory Types

Membrane stores knowledge as MemoryRecord values. Each record has a type that determines its payload schema, lifecycle behavior, and role in retrieval.

Overview

Type	Purpose	Example
episodic	Raw experience capture	Tool calls, errors, agent turns, user messages
working	Current task state	"Auth refactor in progress, tests pending"
entity	Canonical people, files, projects, tools, concepts, and other named things	"auth middleware", `pkg/auth`, "Project Orion"
semantic	Stable facts and preferences	"User prefers Go for backend services"
competence	Learned procedures with success tracking	"To debug auth retries: inspect logs, run focused tests"
plan_graph	Reusable solution structures as directed graphs	Multi-step rollout workflow with dependencies

Episodic records preserve evidence. Entity and semantic records make that evidence addressable. Competence and plan graph records are learned from repeated successful traces. Working records track resumable state.

Base Record Schema

Every memory record shares these fields:

type MemoryRecord struct {
    ID             string
    Type           MemoryType    // episodic | working | entity | semantic | competence | plan_graph
    Sensitivity    Sensitivity   // public | low | medium | high | hyper
    Confidence     float64
    Salience       float64
    Scope          string
    Tags           []string
    CreatedAt      time.Time
    UpdatedAt      time.Time
    Lifecycle      Lifecycle
    Provenance     Provenance
    Relations      []Relation
    Interpretation *Interpretation
    Payload        Payload
    AuditLog       []AuditEntry
}

Relations and graph edges connect records through predicates such as mentions_entity, referenced_by, and derived_from.

Episodic

Episodic memory captures raw experience as time-ordered evidence. It is the source material for later semantic, competence, plan, and entity extraction.

type EpisodicPayload struct {
    Kind         string
    Timeline     []TimelineEvent
    ToolGraph    []ToolNode
    Environment  *EnvironmentSnapshot
    Outcome      OutcomeStatus
    Artifacts    []string
    ToolGraphRef string
}

Warning

Episodic records are immutable once stored. Correct durable knowledge by revising semantic, competence, entity, or plan graph records instead.

Capture Example

capture, err := m.CaptureMemory(ctx, ingestion.CaptureMemoryRequest{
    Source:           "auth-agent",
    SourceKind:       "event",
    Content:          map[string]any{
        "ref":  "thread-1:turn-7",
        "text": "Refactored auth middleware and verified package tests",
    },
    ReasonToRemember: "Keep auth refactor context",
    Summary:          "Refactored auth middleware",
    Tags:             []string{"auth"},
    Sensitivity:      schema.SensitivityLow,
})

Working

Working memory stores resumable task state.

type WorkingPayload struct {
    Kind              string
    ThreadID          string
    State             TaskState
    ActiveConstraints []Constraint
    NextActions       []string
    OpenQuestions     []string
    ContextSummary    string
}

_, err := m.CaptureMemory(ctx, ingestion.CaptureMemoryRequest{
    Source:     "auth-agent",
    SourceKind: "working_state",
    Content: map[string]any{
        "thread_id":       "session-001",
        "state":           "executing",
        "next_actions":    []string{"run tests", "review output"},
        "context_summary": "Refactoring auth middleware",
    },
    Summary:     "Auth refactor in progress",
    Sensitivity: schema.SensitivityLow,
})

Entity

Entity memory stores canonical named things and their aliases. Entity records make retrieval graph-aware: captures can mention an entity, resolve to the canonical record, and return connected memories when that entity appears in a task descriptor.

type EntityPayload struct {
    Kind          string
    CanonicalName string
    PrimaryType   EntityType
    Types         []EntityType
    Aliases       []EntityAlias
    Identifiers   []EntityIdentifier
    Summary       string
}

Built-in entity types include Person, Organization, Agent, Project, Repository, File, Symbol, API, Service, Database, Tool, Task, Incident, Document, URL, Concept, Event, and Other. The ontology is open, so applications may use project-specific strings.

Entity records are usually created by CaptureMemory during interpretation, but they can also be represented directly as MemoryRecord values for revision operations.

Semantic

Semantic memory stores durable facts as subject-predicate-object triples.

type SemanticPayload struct {
    Kind           string
    Subject        string
    Predicate      string
    Object         any
    Validity       Validity
    Evidence       []ProvenanceRef
    RevisionPolicy string
    Revision       *RevisionState
}

_, err := m.CaptureMemory(ctx, ingestion.CaptureMemoryRequest{
    Source:     "auth-agent",
    SourceKind: "observation",
    Content: map[string]any{
        "subject":   "user",
        "predicate": "prefers_language",
        "object":    "Go",
    },
    ReasonToRemember: "Remember user language preference",
    Summary:          "User prefers Go",
    Sensitivity:      schema.SensitivityLow,
})

Semantic records support supersede, fork, contest, retract, and merge.

Competence

Competence memory stores procedural knowledge: triggers, recipe steps, required tools, failure modes, fallbacks, and performance stats.

type CompetencePayload struct {
    Kind          string
    SkillName     string
    Triggers      []Trigger
    Recipe        []RecipeStep
    RequiredTools []string
    FailureModes  []string
    Fallbacks     []string
    Performance   *PerformanceStats
    Version       string
}

Competence records are created by consolidation when the same successful tool pattern appears repeatedly. Retrieval scores them by applicability, success rate, and recency.

Plan Graph

Plan graph memory stores reusable solution structures as directed graphs of action nodes and dependency edges.

type PlanGraphPayload struct {
    Kind          string
    PlanID        string
    Version       string
    Intent        string
    Constraints   map[string]any
    InputsSchema  map[string]any
    OutputsSchema map[string]any
    Nodes         []PlanNode
    Edges         []PlanEdge
    Metrics       *PlanMetrics
}

Plan graphs are extracted from episodic tool graphs with enough structure to reuse. Retrieval scores them with selector metadata and, when configured, embedding similarity.

Consolidation Flow

Capture evidence

Runtime events, tool outputs, observations, and working state are captured through CaptureMemory.

Interpret and link

Capture interpretation extracts mentions, resolves entities, and writes graph edges when configured.

Consolidate durable knowledge

Background jobs promote eligible episodic traces into semantic facts, competence records, and plan graphs.

Retrieve graph context

RetrieveGraph returns ranked roots and linked records subject to trust, salience, and graph limits.

Revise and reinforce

Durable records can be revised explicitly, and useful records can be reinforced to increase future salience.

Overview​

Base Record Schema​

Episodic​

Capture Example​

Working​

Entity​

Semantic​

Competence​

Plan Graph​

Consolidation Flow​