| title | Memory Types |
|---|---|
| description | The six typed memory categories in Membrane: episodic, working, entity, semantic, competence, and plan graph. |
Membrane stores knowledge as MemoryRecord values. Each record has a type that determines its payload schema, lifecycle behavior, and role in retrieval.
| 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.
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 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
}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 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 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
}Identifier namespaces are normalized to lowercase before storage and lookup;
identifier values are trimmed but remain case-sensitive.
Capture and retrieval both recognize explicit identifier tokens such as
github:BennettSchwartz/orchid and repo_path:pkg/auth, so identifiers can
seed canonical entity resolution even when the display name is absent.
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.
Direct entity records must include a non-empty canonical_name; the schema validator rejects entity payloads without one before they can be stored.
Semantic memory stores durable facts as subject-predicate-object triples. Predicates are canonicalized to lower snake case before storage and duplicate matching, which keeps model- or user-provided spellings aligned.
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,
})When observations create semantic records, subject terms and string object terms are canonicalized to entity IDs when a same-scope entity exists, or when an unscoped global entity is the best match.
Semantic records support supersede, fork, contest, retract, and merge.
Direct semantic records must include non-empty subject and predicate fields, a non-null object, and a validity mode of global, conditional, or timeboxed; MemoryRecord.Validate rejects malformed semantic payloads before storage.
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 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.
Runtime events, tool outputs, observations, and working state are captured through `CaptureMemory`. Capture interpretation extracts mentions, resolves entities, and writes graph edges when configured. Background jobs promote eligible episodic traces into semantic facts, competence records, and plan graphs. `RetrieveGraph` returns ranked roots and linked records subject to trust, salience, and graph limits. Durable records can be revised explicitly, and useful records can be reinforced to increase future salience.