Architecture

​

Overview

+------------------+     +------------------+     +----------------------+
|  Ingestion Plane |---->|   Policy Plane   |---->| Storage & Retrieval  |
+------------------+     +------------------+     +----------------------+
        |                        |                         |
   Events, tool            Classification,            SQLCipher (encrypted),
   outputs, obs.,          sensitivity,               audit trails,
   working state           decay profiles             trust-gated access

​

Three logical planes

​

Ingestion plane

• Classifier — determines which memory type (episodic, working, semantic, etc.) a candidate belongs to based on its shape.
• Policy engine — assigns sensitivity, confidence, initial salience, and a type-specific decay profile. Tool outputs receive an initial confidence of 0.9; observations receive 0.7; events receive 0.8.
• Store write — persists the record and its initial audit log entry.

​

Policy plane

• Sensitivity assignment — defaults to the configured default_sensitivity ("low" out of the box) unless overridden per-record. Sensitivity is stored on the record and used by the trust filter at retrieval time.
• Decay profile assignment — each memory type gets a different exponential decay half-life: episodic records decay in ~1 hour by default; working memory in ~1 day; semantic, competence, and plan-graph records in ~30 days.

​

Storage and retrieval plane

working → semantic → competence → plan_graph → episodic

​

Subsystems

​

How they wire together

// Membrane wires all subsystems together and exposes the unified API surface.
type Membrane struct {
	config *Config
	store  storage.Store

	ingestion     *ingestion.Service
	retrieval     *retrieval.Service
	decay         *decay.Service
	revision      *revision.Service
	consolidation *consolidation.Service
	metrics       *metrics.Collector
	embedding     *embedding.Service

	decayScheduler  *decay.Scheduler
	consolScheduler *consolidation.Scheduler
}

​

Storage model

​

Backends

​

Record structure

• ID — UUID generated at ingestion time
• Type — one of episodic, working, semantic, competence, plan_graph
• Sensitivity — public, low, medium, high, or hyper
• Confidence — epistemic confidence score (0.0–1.0), set by the policy engine at ingestion
• Salience — current relevance score (0.0–1.0), modified by decay, reinforcement, and penalization
• Payload — type-specific JSON struct stored inside the authoritative record
• Provenance — list of source references describing where the record came from
• Relations — directed edges to other records: supersedes, derived_from, contested_by, supports, contradicts
• AuditLog — append-only list of every action taken on the record

​

Relationship graph

​

Deployment tiers

​

Background jobs

​

Decay curve

// Exponential computes exponential decay: salience * 2^(-elapsed/halfLife),
// floored at MinSalience.
func Exponential(currentSalience, elapsedSeconds float64, profile schema.DecayProfile) float64 {
	halfLife := float64(profile.HalfLifeSeconds)
	if halfLife <= 0 {
		return math.Max(currentSalience, profile.MinSalience)
	}
	decayed := currentSalience * math.Exp(-elapsedSeconds*math.Log(2)/halfLife)
	return math.Max(decayed, profile.MinSalience)
}

​

Consolidation pipeline

1. Episodic consolidator — compresses old episodic records by reducing their salience once they exceed an age threshold.
2. Semantic consolidator — scans episodic records for observation-like patterns and promotes them to semantic facts; reinforces existing duplicates rather than creating new ones.
3. Semantic extractor (optional, requires LLM) — sends batches of episodic records to a chat completion endpoint and stores the extracted subject-predicate-object triples as semantic memory.
4. Competence consolidator — identifies repeated successful episodic patterns and promotes them to competence records with success-rate tracking.
5. Plan-graph consolidator — extracts multi-step tool-call sequences from episodic tool graphs and stores them as reusable plan graphs.

​

Security model

​

Encryption at rest

​

Transport security

​

Authentication

​

Rate limiting

​

Trust-aware retrieval

• MaxSensitivity — records at a higher sensitivity level are excluded entirely; records exactly one level above MaxSensitivity may be returned in redacted form (metadata only, payload stripped).
• Scopes — if the trust context specifies scopes, only records whose Scope matches are returned. Records with an empty scope are unscoped and visible to all callers.
• Authenticated — carried in the trust context for policy decisions.

// sensitivityOrder maps sensitivity levels to a numeric ordering.
var sensitivityOrder = map[schema.Sensitivity]int{
	schema.SensitivityPublic: 0,
	schema.SensitivityLow:    1,
	schema.SensitivityMedium: 2,
	schema.SensitivityHigh:   3,
	schema.SensitivityHyper:  4,
}

​

Input validation

​

gRPC API surface

​

Observability

{
  "total_records": 142,
  "records_by_type": {
    "episodic": 80,
    "semantic": 35,
    "competence": 15,
    "plan_graph": 7,
    "working": 5
  },
  "avg_salience": 0.62,
  "avg_confidence": 0.78,
  "active_records": 130,
  "pinned_records": 3,
  "total_audit_entries": 890,
  "memory_growth_rate": 0.15,
  "retrieval_usefulness": 0.42,
  "competence_success_rate": 0.85,
  "plan_reuse_frequency": 2.3,
  "revision_rate": 0.08
}

​

Next steps