Membrane

https://membrane.gustycube.com
Admin
Membrane gives long-lived LLM agents structured, revisable memory with built-in decay, trust-gated...
Tokens:73,439
Snippets:671
Trust Score:5.5
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install Membrane Go Library

Source: https://membrane.gustycube.com/guides/go-library

Use 'go get' to install the Membrane Go library. This is the first step to integrating Membrane into your Go project.

```bash
go get github.com/BennettSchwartz/membrane  

```

--------------------------------

### Complete Go Example

Source: https://membrane.gustycube.com/guides/go-library

A comprehensive example demonstrating the initialization, starting, capturing memory, and retrieving graph data using the Membrane Go library. Ensure all necessary packages are imported.

```go
package main  
  
import (  
    "context"  
    "fmt"  
    "log"  
  
    "github.com/BennettSchwartz/membrane/pkg/ingestion"  
    "github.com/BennettSchwartz/membrane/pkg/membrane"  
    "github.com/BennettSchwartz/membrane/pkg/retrieval"  
    "github.com/BennettSchwartz/membrane/pkg/schema"  
)  
  
func main() {  
    cfg := membrane.DefaultConfig()  
    cfg.DBPath = "my-agent.db"  
  
    m, err := membrane.New(cfg)  
    if err != nil {  
        log.Fatal(err)  
    }  
    defer m.Stop()  
  
    ctx := context.Background()  
    if err := m.Start(ctx); err != nil {  
        log.Fatal(err)  
    }  
  
    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,  
    })  
    if err != nil {  
        log.Fatal(err)  
    }  
  
    graph, err := m.RetrieveGraph(ctx, &retrieval.RetrieveGraphRequest{  
        TaskDescriptor: "debug auth",  
        Trust: retrieval.NewTrustContext(  
            schema.SensitivityMedium,  
            true,  
            "auth-agent",  
            nil,  
        ),  
        MemoryTypes: []schema.MemoryType{  
            schema.MemoryTypeEntity,  
            schema.MemoryTypeSemantic,  
            schema.MemoryTypeEpisodic,  
        },  
        RootLimit: 5,  
        NodeLimit: 20,  
        MaxHops:   1,  
    })  
    if err != nil {  
        log.Fatal(err)  
    }  
  
    fmt.Printf("Captured %s and retrieved %d graph nodes\n",  
        capture.PrimaryRecord.ID,  
        len(graph.Nodes),  
    )  
}  

```

--------------------------------

### Development Setup and Testing

Source: https://membrane.gustycube.com/sdks/python

Commands for setting up the development environment and running tests. Install dependencies and execute pytest.

```bash
cd clients/python  
pip install -e .[dev]  
pytest  
```

--------------------------------

### Write First Memory Loop with Membrane Go Library

Source: https://membrane.gustycube.com/quickstart

An example of how to initialize Membrane, start it, capture memory, and retrieve data within a Go application.

```go
package main  

import (  
    "context"  
    "fmt"  
    "log"  

    "github.com/BennettSchwartz/membrane/pkg/ingestion"  
    "github.com/BennettSchwartz/membrane/pkg/membrane"  
    "github.com/BennettSchwartz/membrane/pkg/retrieval"  
    "github.com/BennettSchwartz/membrane/pkg/schema"  
)  

func main() {  
    cfg := membrane.DefaultConfig()  
    cfg.DBPath = "my-agent.db"  

    m, err := membrane.New(cfg)  
    if err != nil {  
        log.Fatal(err)  
    }  
    defer m.Stop()  

    ctx := context.Background()  
    if err := m.Start(ctx); err != nil {  
        log.Fatal(err)  
    }  

    capture, err := m.CaptureMemory(ctx, ingestion.CaptureMemoryRequest{  
        Source:           "build-agent",  
        SourceKind:       "tool_output",  
        Content:          map[string]any{  
            "tool":   "go test",  
            "args":   []string{"./..."},  
            "result": "auth package passed",  
        },  
        Context:          map[string]any{"thread_id": "session-001"},  
        ReasonToRemember: "Keep successful test context for future auth work",  
        Summary:          "Auth package tests passed",  
        Tags:             []string{"auth", "tests"},  
        Scope:            "project-auth",  
        Sensitivity:      schema.SensitivityLow,  
    })  
    if err != nil {  
        log.Fatal(err)  
    }  
    fmt.Printf("Captured primary record: %s\n", capture.PrimaryRecord.ID)  

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

    graph, err := m.RetrieveGraph(ctx, &retrieval.RetrieveGraphRequest{  
        TaskDescriptor: "fix auth build error",  
        Trust: retrieval.NewTrustContext(  
            schema.SensitivityMedium,  
            true,  
            "build-agent",  
            []string{"project-auth"},  
        ),  
        MemoryTypes: []schema.MemoryType{  
            schema.MemoryTypeEntity,  
            schema.MemoryTypeSemantic,  
            schema.MemoryTypeCompetence,  
            schema.MemoryTypeEpisodic,  
        },  
        RootLimit: 10,  
        NodeLimit: 25,  
        EdgeLimit: 100,  
        MaxHops:   1,  
    })  
    if err != nil {  
        log.Fatal(err)  
    }  

    for _, node := range graph.Nodes {  
        fmt.Printf("Found: %s (type=%s, root=%t, hop=%d)\n",  
            node.Record.ID,  
            node.Record.Type,  
            node.Root,  
            node.Hop,  
        )  
    }  
}  

```

--------------------------------

### Get and Print Metrics

Source: https://membrane.gustycube.com/sdks/python

Retrieve and display metrics from the client. This example shows how to get all metrics and print the total number of records.

```python
metrics = client.get_metrics()  
print(metrics["total_records"])  
```

--------------------------------

### TypeScript Client Installation and Usage

Source: https://membrane.gustycube.com/api/overview

Instructions for installing and using the official TypeScript client for the Membrane API, including examples for capturing memories and retrieving data.

```APIDOC
## Connecting with TypeScript

Install the official TypeScript client:
```
npm install @bennettschwartz/membrane
```

```typescript
import { MembraneClient, Sensitivity } from "@bennettschwartz/membrane";

const client = new MembraneClient("localhost:9090", { apiKey: "your-key" });

// Capture a memory candidate
const capture = await client.captureMemory({
  ref: "task#1",
  text: "Refactored auth middleware and verified package tests",
}, {
  sourceKind: "event",
  summary: "Refactored auth middleware",
  tags: ["auth", "tests"],
});

// Retrieve with trust context
const graph = await client.retrieveGraph("auth debugging", {
  trust: {
    max_sensitivity: Sensitivity.MEDIUM,
    authenticated: true,
    actor_id: "ts-agent",
    scopes: [],
  },
  memoryTypes: ["entity", "semantic", "competence"],
});

client.close();
```
```

--------------------------------

### Install Python SDK

Source: https://membrane.gustycube.com/sdks/python

Install the Python SDK using pip. Use the `[dev]` extra for development dependencies.

```bash
pip install -e clients/python
```

```bash
pip install -e clients/python[dev]
```

--------------------------------

### Start Membrane Daemon with Custom Configuration

Source: https://membrane.gustycube.com/quickstart

Start the Membrane daemon using a custom configuration file.

```bash
./bin/membraned --config /path/to/config.yaml  

```

--------------------------------

### Create and Start Membrane Instance

Source: https://membrane.gustycube.com/guides/go-library

Initialize a Membrane instance with a default configuration, specifying the database path. Ensure to start the instance and defer its stopping to properly manage resources.

```go
cfg := membrane.DefaultConfig()  
cfg.DBPath = "my-agent.db"  
  
m, err := membrane.New(cfg)  
if err != nil {  
    log.Fatal(err)  
}  
  
ctx := context.Background()  
if err := m.Start(ctx); err != nil {  
    log.Fatal(err)  
}  
defer m.Stop()  

```

--------------------------------

### Install Python Client

Source: https://membrane.gustycube.com/api/overview

Install the Membrane Python client using pip.

```bash
pip install -e clients/python
```

--------------------------------

### Quick Start with Python SDK

Source: https://membrane.gustycube.com/sdks/python

Demonstrates capturing memory and retrieving graph data using the MembraneClient. Ensure the client is properly initialized and closed.

```python
from membrane import MembraneClient, Sensitivity, SourceKind, TrustContext

client = MembraneClient("localhost:9090")

capture = client.capture_memory(
    {
        "ref": "src/auth.py",
        "text": "Refactored auth middleware and verified package tests",
        "file": "src/auth.py",
    },
    source_kind=SourceKind.EVENT,
    reason_to_remember="Keep the auth refactor available for future debugging",
    summary="Refactored auth middleware",
    sensitivity=Sensitivity.LOW,
    tags=["auth", "python"],
)
print(capture.primary_record.id)

trust = TrustContext(
    max_sensitivity=Sensitivity.MEDIUM,
    authenticated=True,
    actor_id="agent-1",
)

graph = client.retrieve_graph(
    "debug auth",
    trust=trust,
    memory_types=["entity", "semantic", "competence", "episodic"],
    root_limit=5,
    node_limit=20,
    max_hops=1,
)

for node in graph.nodes:
    print(f"[{node.record.type.value}] {node.record.id} root={node.root} hop={node.hop}")

client.close()
```

--------------------------------

### Membrane Configuration YAML Example

Source: https://membrane.gustycube.com/api/go/membrane

An example of how to configure the Membrane daemon using a YAML file. This includes settings for backend, database connection, network, and various operational parameters.

```yaml
backend: postgres
postgres_dsn: "postgres://user:pass@localhost:5432/membrane"
listen_addr: ":9090"
decay_interval: 1h
consolidation_interval: 6h
default_sensitivity: low
selection_confidence_threshold: 0.7
graph_default_root_limit: 10
graph_default_node_limit: 25
graph_default_edge_limit: 100
graph_default_max_hops: 1
embedding_endpoint: "https://api.openai.com/v1/embeddings"
embedding_model: "text-embedding-3-small"
embedding_dimensions: 1536
llm_endpoint: "https://api.openai.com/v1/chat/completions"
llm_model: "gpt-5-mini"
ingest_llm_enabled: true
ingest_llm_endpoint: "https://api.openai.com/v1/chat/completions"
ingest_llm_model: "gpt-5-mini"
rate_limit_per_second: 100
```

--------------------------------

### Start Membrane Daemon with Postgres

Source: https://membrane.gustycube.com/quickstart

Start the Membrane daemon using a PostgreSQL database with a specified data source name.

```bash
docker compose up -d  
./bin/membraned --postgres-dsn postgres://membrane:membrane@localhost:5432/membrane_test?sslmode=disable  

```

--------------------------------

### Install Membrane SDK (pip)

Source: https://membrane.gustycube.com/quickstart

Install the Membrane Python client library using pip. This command installs the package in editable mode.

```bash
pip install -e clients/python  
```

--------------------------------

### Start Membrane Daemon with Default SQLite Storage

Source: https://membrane.gustycube.com/guides/deployment

Run the membraned binary without any arguments to start the daemon with default SQLite storage. A 'membrane.db' file will be created in the current working directory.

```bash
./bin/membraned  
```

--------------------------------

### CaptureMemory Request Example

Source: https://membrane.gustycube.com/api/go/ingestion

Example of constructing a CaptureMemoryRequest. Ensure all required fields like Source, SourceKind, and Content are provided. Optional fields can be used to enrich the capture.

```go
capture, err := m.CaptureMemory(ctx, ingestion.CaptureMemoryRequest{  
    Source:           "auth-agent",  
    SourceKind:       "tool_output",  
    Content:          map[string]any{  
        "tool_name": "go test",  
        "args":      map[string]any{"packages": []string{"./pkg/auth"}},  
        "result":    map[string]any{"exit_code": 0},  
    },  
    ReasonToRemember: "Successful auth package verification",  
    Summary:          "Auth package tests passed",  
    Tags:             []string{"auth", "tests"},  
    Scope:            "project-auth",  
    Sensitivity:      schema.SensitivityLow,  
})

```

--------------------------------

### Start and Stop Membrane Lifecycle

Source: https://membrane.gustycube.com/api/go/membrane

The `Start` method begins background decay and consolidation schedulers, and backfills embeddings if configured. The `Stop` method shuts down schedulers and closes the store.

```go
func (m *Membrane) Start(ctx context.Context) error
func (m *Membrane) Stop() error

```

--------------------------------

### RetrieveByID Usage Example

Source: https://membrane.gustycube.com/api/go/retrieval

Example of how to use RetrieveByID and handle potential errors like record not found or access denied.

```go
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  
}  


```

--------------------------------

### Clone Membrane Repository

Source: https://membrane.gustycube.com/quickstart

Clone the Membrane repository to your local machine to get started.

```bash
git clone https://github.com/BennettSchwartz/membrane.git  
cd membrane  

```

--------------------------------

### Multi-step Workflow Example

Source: https://membrane.gustycube.com/concepts/plan-graphs

This Go code demonstrates a multi-step workflow involving ingesting an episodic record, extracting a plan graph, retrieving plan graphs for a task, and reinforcing a plan after successful execution.

```go
// 1. An episodic record with a complex tool graph is ingested automatically
//    during agent execution. It might look like this in memory:
episodicPayload := &schema.EpisodicPayload{
    Kind: "episodic",
    Timeline: []schema.TimelineEvent{
        {T: t1, EventKind: "setup_project", Ref: "step#1", Summary: "Init repo"},
        {T: t2, EventKind: "install_deps",  Ref: "step#2", Summary: "npm install"},
        {T: t3, EventKind: "build",         Ref: "step#3", Summary: "npm run build"},
    },
    ToolGraph: []schema.ToolNode{
        {ID: "n1", Tool: "git_init",    Args: map[string]any{"path": "./"}},
        {ID: "n2", Tool: "npm_install", Args: map[string]any{}, DependsOn: []string{"n1"}},
        {ID: "n3", Tool: "npm_build",   Args: map[string]any{}, DependsOn: []string{"n2"}},
    },
    Outcome: schema.OutcomeStatusSuccess,
}

// 2. The consolidation pipeline extracts a plan graph from this episode.
//    The resulting plan graph will have:
//    - Node n1: Op="git_init"
//    - Node n2: Op="npm_install"
//    - Node n3: Op="npm_build"
//    - Edge n1→n2: kind=control
//    - Edge n2→n3: kind=control
//    - Intent: "setup_project" (from first timeline event kind)

// 3. Retrieve plan graphs for a task
resp, _ := m.RetrieveGraph(ctx, &retrieval.RetrieveGraphRequest{
    TaskDescriptor: "set up a new project",
    Trust: &retrieval.TrustContext{
        MaxSensitivity: schema.SensitivityLow,
        Authenticated:  true,
    },
    MemoryTypes: []schema.MemoryType{
        schema.MemoryTypePlanGraph,
    },
    RootLimit: 5,
    NodeLimit: 10,
    MaxHops:   0,
})

for _, node := range resp.Nodes {
    r := node.Record
    if p, ok := r.Payload.(*schema.PlanGraphPayload); ok {
        fmt.Printf("Plan: %s (intent=%s, executions=%d, failure_rate=%.2f)\n",
            p.PlanID,
            p.Intent,
            p.Metrics.ExecutionCount,
            p.Metrics.FailureRate,
        )
        for _, node := range p.Nodes {
            fmt.Printf("  Node %s: op=%s\n", node.ID, node.Op)
        }
        for _, edge := range p.Edges {
            fmt.Printf("  Edge %s → %s (%s)\n", edge.From, edge.To, edge.Kind)
        }
    }
}

// 4. Reinforce the plan after a successful run
if len(resp.RootIDs) > 0 {
    m.Reinforce(ctx, resp.RootIDs[0], "project-agent", "plan completed successfully")
}

```

--------------------------------

### Install OpenClaw Membrane Plugin

Source: https://membrane.gustycube.com/sdks/openclaw-plugin

Install the plugin using npm in your OpenClaw extensions directory. The `brainplex init` command automatically detects and configures installed plugins.

```bash
npm install @vainplex/openclaw-membrane
```

```bash
npx brainplex init
```

--------------------------------

### Install pgvector Extension

Source: https://membrane.gustycube.com/guides/deployment

SQL command to install the pgvector extension if you are using an existing PostgreSQL instance.

```sql
CREATE EXTENSION IF NOT EXISTS vector;

```

--------------------------------

### New Membrane Instance

Source: https://membrane.gustycube.com/api/go/membrane

Initializes all subsystems from a Config and returns a ready-to-start Membrane instance. It's crucial to defer the Stop() call and start the membrane with a context.

```APIDOC
## New Membrane Instance

### Description
Initializes all subsystems from `Config` and returns a ready-to-start `Membrane`. Ensure `Stop()` is deferred and the membrane is started with a context.

### Function Signature
```go
func New(cfg *Config) (*Membrane, error)
```

### Usage Example
```go
cfg := membrane.DefaultConfig()
cfg.DBPath = "my-agent.db"

m, err := membrane.New(cfg)
if err != nil {
    log.Fatal(err)
}
defer m.Stop()

if err := m.Start(context.Background()); err != nil {
    log.Fatal(err)
}
```
```

--------------------------------

### Start Membrane Daemon with SQLite

Source: https://membrane.gustycube.com/quickstart

Start the Membrane daemon using the default SQLite database. It will listen on port 9090.

```bash
./bin/membraned  

```

--------------------------------

### Start Docker Compose Database

Source: https://membrane.gustycube.com/guides/deployment

Command to start the database services defined in docker-compose.yml in detached mode.

```bash
docker compose up -d

```

--------------------------------

### Capture Semantic Memory Example

Source: https://membrane.gustycube.com/concepts/memory-types

Demonstrates capturing a semantic memory record for user language preference using CaptureMemory.

```go
_ , 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,
})

```

--------------------------------

### Install Membrane TypeScript Client

Source: https://membrane.gustycube.com/api/overview

Install the official TypeScript client using npm. This is the first step to integrating Membrane into your TypeScript project.

```bash
npm install @bennettschwartz/membrane  

```

--------------------------------

### Example Metrics Snapshot

Source: https://membrane.gustycube.com/api/metrics

An example JSON payload representing a snapshot of the memory substrate's health and behavioral metrics.

```json
{
  "collected_at": "2026-02-05T14:23:10Z",
  "total_records": 160,
  "records_by_type": {
    "episodic": 80,
    "entity": 18,
    "semantic": 35,
    "competence": 15,
    "plan_graph": 7,
    "working": 5
  },
  "avg_salience": 0.62,
  "avg_confidence": 0.78,
  "salience_distribution": {
    "0.0-0.2": 14,
    "0.2-0.4": 22,
    "0.4-0.6": 34,
    "0.6-0.8": 50,
    "0.8-1.0": 40
  },
  "active_records": 148,
  "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
}

```

--------------------------------

### Initialize and Use MembraneClient in TypeScript

Source: https://membrane.gustycube.com/api/overview

Demonstrates how to initialize the MembraneClient with connection details and an API key. Includes examples for capturing a memory candidate and retrieving a graph with trust context.

```typescript
import { MembraneClient, Sensitivity } from "@bennettschwartz/membrane";  
  
const client = new MembraneClient("localhost:9090", { apiKey: "your-key" });  
  
// Capture a memory candidate  
const capture = await client.captureMemory({  
  ref: "task#1",  
  text: "Refactored auth middleware and verified package tests",  
}, {  
  sourceKind: "event",  
  summary: "Refactored auth middleware",  
  tags: ["auth", "tests"],  
});  
  
// Retrieve with trust context  
const graph = await client.retrieveGraph("auth debugging", {  
  trust: {  
    max_sensitivity: Sensitivity.MEDIUM,  
    authenticated: true,  
    actor_id: "ts-agent",  
    scopes: [],  
  },  
  memoryTypes: ["entity", "semantic", "competence"],  
});  
  
client.close();  

```

--------------------------------

### Quick Start with TypeScript SDK

Source: https://membrane.gustycube.com/sdks/typescript

Initialize the MembraneClient and perform basic operations like capturing memory and retrieving a graph. Ensure you replace 'your-api-key' with your actual API key.

```typescript
import {  
  MembraneClient,  
  Sensitivity,  
  SourceKind,  
} from "@bennettschwartz/membrane";  
  
const client = new MembraneClient("localhost:9090", {  
  apiKey: "your-api-key",  
});  
  
const capture = await client.captureMemory(  
  {  
    ref: "src/auth.ts",  
    text: "Refactored auth middleware and verified package tests",  
    file: "src/auth.ts",  
  },  
  {  
    sourceKind: SourceKind.EVENT,  
    reasonToRemember: "Keep the auth refactor available for future debugging",  
    summary: "Refactored auth middleware",  
    sensitivity: Sensitivity.LOW,  
    tags: ["auth", "typescript"],  
  }  
);  
  
const graph = await client.retrieveGraph("debug auth", {  
  trust: {  
    max_sensitivity: Sensitivity.MEDIUM,  
    authenticated: true,  
    actor_id: "agent-1",  
    scopes: [],  
  },  
  memoryTypes: ["entity", "semantic", "competence", "episodic"],  
  rootLimit: 10,  
  nodeLimit: 25,  
  edgeLimit: 100,  
  maxHops: 1,  
});  
  
console.log(capture.primary_record.id, graph.nodes.length);  
client.close();  

```

--------------------------------

### RetrieveGraph Go Example

Source: https://membrane.gustycube.com/api/retrieval

Demonstrates how to call the RetrieveGraph API in Go, including setting trust context, memory types, and limits. Handles potential errors and iterates through the returned nodes.

```go
resp, err := m.RetrieveGraph(ctx, &retrieval.RetrieveGraphRequest{
    TaskDescriptor: "fix auth build error",
    Trust: retrieval.NewTrustContext(
        schema.SensitivityMedium,
        true,
        "build-agent",
        []string{"project-auth"},
    ),
    MemoryTypes: []schema.MemoryType{
        schema.MemoryTypeEntity,
        schema.MemoryTypeSemantic,
        schema.MemoryTypeCompetence,
        schema.MemoryTypeEpisodic,
    },
    RootLimit: 10,
    NodeLimit: 25,
    EdgeLimit: 100,
    MaxHops:   1,
})
if err != nil {
    log.Fatal(err)
}

for _, node := range resp.Nodes {
    fmt.Printf("Found: %s (type=%s, root=%t, hop=%d)\n",
        node.Record.ID,
        node.Record.Type,
        node.Root,
        node.Hop,
    )
}

```

--------------------------------

### Initialize Membrane with Configuration

Source: https://membrane.gustycube.com/api/go/membrane

Initializes all subsystems from a `Config` object. Ensure to handle potential errors during initialization and defer the `Stop` method for graceful shutdown. The `Start` method should be called with a `context.Context` to begin background schedulers.

```go
cfg := membrane.DefaultConfig()
cfg.DBPath = "my-agent.db"

m, err := membrane.New(cfg)
if err != nil {
    log.Fatal(err)
}
deferr m.Stop()

if err := m.Start(context.Background()); err != nil {
    log.Fatal(err)
}

```

--------------------------------

### Capture Working Memory Example

Source: https://membrane.gustycube.com/concepts/memory-types

Demonstrates capturing working memory to store resumable task state. Use this for tracking ongoing tasks and their progress.

```go
_ , 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,
})

```

--------------------------------

### Full YAML Configuration Example

Source: https://membrane.gustycube.com/guides/configuration

This snippet shows all available fields in the Membrane YAML configuration file. Fields not present will use default values.

```yaml
backend: "sqlite"  
db_path: "membrane.db"  
# postgres_dsn: "postgres://membrane:membrane@localhost:5432/membrane?sslmode=disable"  
listen_addr: ":9090"  
decay_interval: "1h"  
consolidation_interval: "6h"  
default_sensitivity: "low"  
selection_confidence_threshold: 0.7  
graph_default_root_limit: 10  
graph_default_node_limit: 25  
graph_default_edge_limit: 100  
graph_default_max_hops: 1  
  
# Optional embedding-backed retrieval (Postgres only)  
# embedding_endpoint: "https://api.openai.com/v1/embeddings"  
# embedding_model: "text-embedding-3-small"  
# embedding_dimensions: 1536  
# embedding_api_key: ""   # or set MEMBRANE_EMBEDDING_API_KEY  
  
# Optional LLM-backed semantic extraction (Postgres only)  
# llm_endpoint: "https://api.openai.com/v1/chat/completions"  
# llm_model: "gpt-5-mini"  
# llm_api_key: ""         # or set MEMBRANE_LLM_API_KEY  
  
# Optional ingest-side interpretation for CaptureMemory  
# ingest_llm_enabled: true  
# ingest_llm_endpoint: "https://api.openai.com/v1/chat/completions"  
# ingest_llm_model: "gpt-5-mini"  
# ingest_llm_api_key: ""  # or set MEMBRANE_INGEST_LLM_API_KEY  
  
# Security (prefer environment variables for keys)  
# encryption_key: ""       # or set MEMBRANE_ENCRYPTION_KEY  
# api_key: ""              # or set MEMBRANE_API_KEY  
# tls_cert_file: ""  
# tls_key_file: ""  
rate_limit_per_second: 100  

```

--------------------------------

### Service Struct and Constructors

Source: https://membrane.gustycube.com/api/go/ingestion

Defines the Service struct and its constructors. Use NewService for standard setup or NewServiceWithInterpreter to enable LLM-backed interpretation.

```go
type Service struct { ... }  

func NewService(store storage.Store, classifier *Classifier, policy *PolicyEngine) *Service  
func NewServiceWithInterpreter(store storage.Store, classifier *Classifier, policy *PolicyEngine, interpreter Interpreter) *Service  
```

--------------------------------

### Pass API Key from Python Client

Source: https://membrane.gustycube.com/guides/security

Example of how to initialize a Membrane client in Python, passing the API key from environment variables.

```python
client = MembraneClient("localhost:9090", api_key=os.environ["MEMBRANE_API_KEY"])
```

--------------------------------

### Start Membrane Daemon with Overridden Settings

Source: https://membrane.gustycube.com/guides/deployment

Override specific settings like the database path and listen address directly via command-line flags without using a configuration file.

```bash
./bin/membraned --db /data/membrane.db --addr :8080  
```

--------------------------------

### GetMetrics Observability Response Example

Source: https://membrane.gustycube.com/architecture

This is an example response from the GetMetrics method, illustrating the structure and types of observability data available. It includes counts of records by type, average salience and confidence, and various growth and rate metrics.

```json
{
  "total_records": 160,
  "records_by_type": {
    "episodic": 80,
    "entity": 18,
    "semantic": 35,
    "competence": 15,
    "plan_graph": 7,
    "working": 5
  },
  "avg_salience": 0.62,
  "avg_confidence": 0.78,
  "active_records": 148,
  "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

}
```

--------------------------------

### Start Membrane Daemon with Custom Configuration File

Source: https://membrane.gustycube.com/guides/deployment

Load a custom YAML configuration file using the --config flag. Command-line flags will override any settings present in the configuration file.

```bash
./bin/membraned --config /etc/membrane/config.yaml  
```

--------------------------------

### Get Default Configuration

Source: https://membrane.gustycube.com/api/go/membrane

Returns default configurations for SQLite storage, daemon listen address, schedulers, retrieval limits, and policy settings.

```go
func DefaultConfig() *Config

```

--------------------------------

### Capture Episodic Memory Example

Source: https://membrane.gustycube.com/concepts/memory-types

Demonstrates how to capture episodic memory, storing raw experience with details like source, content, and reason for remembering. Use this for raw, time-ordered evidence.

```go
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,
})

```

--------------------------------

### Development Commands for TypeScript SDK

Source: https://membrane.gustycube.com/sdks/typescript

Run these commands in the terminal to install dependencies, synchronize proto files, perform type checking, run tests, and build the TypeScript SDK.

```bash
cd clients/typescript  
npm install  
npm run check:proto-sync  
npm run typecheck  
npm run test  
npm run build  

```

--------------------------------

### Pass API Key from TypeScript Client

Source: https://membrane.gustycube.com/guides/security

Example of how to initialize a Membrane client in TypeScript, passing the API key from environment variables.

```typescript
const client = new MembraneClient("localhost:9090", {
  apiKey: process.env.MEMBRANE_API_KEY,
});
```

--------------------------------

### Configure MembraneClient with Options

Source: https://membrane.gustycube.com/sdks/typescript

Instantiate the MembraneClient with custom options, including TLS, CA certificate path, API key, and request timeout. This example demonstrates a secure connection to a remote Membrane daemon.

```typescript
const client = new MembraneClient("membrane.example.com:443", {  
  tls: true,  
  tlsCaCertPath: "/path/to/ca.pem",  
  apiKey: process.env.MEMBRANE_API_KEY,  
  timeoutMs: 10_000,  
});  

```

--------------------------------

### Capture Memory Example

Source: https://membrane.gustycube.com/sdks/python

Demonstrates how to capture memory using the Membrane Python SDK. This includes providing reference, text, file, source kind, reason to remember, summary, sensitivity, and tags.

```APIDOC
## capture_memory

### Description
Captures a memory record with specified details.

### Method Signature
`client.capture_memory(content, source_kind, reason_to_remember, summary, sensitivity, tags)`

### Parameters
- **content** (dict) - Required - A dictionary containing memory details like 'ref', 'text', and 'file'.
- **source_kind** (SourceKind) - Required - The kind of source for the memory (e.g., EVENT).
- **reason_to_remember** (str) - Required - The reason for remembering this memory.
- **summary** (str) - Required - A brief summary of the memory.
- **sensitivity** (Sensitivity) - Required - The sensitivity level of the memory (e.g., LOW).
- **tags** (list[str]) - Optional - A list of tags associated with the memory.

### Request Example
```python
client.capture_memory(
    {
        "ref": "src/auth.py",
        "text": "Refactored auth middleware and verified package tests",
        "file": "src/auth.py",
    },
    source_kind=SourceKind.EVENT,
    reason_to_remember="Keep the auth refactor available for future debugging",
    summary="Refactored auth middleware",
    sensitivity=Sensitivity.LOW,
    tags=["auth", "python"],
)
```

### Response
- **primary_record.id** (str) - The ID of the primary memory record captured.
```

--------------------------------

### Store, Consolidate, Retrieve, and Reinforce Competence Records

Source: https://membrane.gustycube.com/concepts/competence-learning

This Go example demonstrates the full lifecycle of competence learning: capturing episodic memories, triggering consolidation to create competence records, retrieving competences for a task, and reinforcing successful ones. Ensure `consolidationSvc` and `m` (Membrane client) are properly initialized.

```go
// 1. Capture a successful episodic record with a tool graph
_, _ = m.CaptureMemory(ctx, ingestion.CaptureMemoryRequest{
    Source:     "build-agent",
    SourceKind: "tool_output",
    Content: map[string]any{
        "tool_name": "go test",
        "args":      map[string]any{"packages": []string{"./pkg/auth"}},
        "result":    map[string]any{"exit_code": 0, "stdout": "ok ./pkg/auth"},
    },
    ReasonToRemember: "Successful auth test procedure",
    Summary:          "Auth package tests passed",
    Tags:             []string{"build", "auth", "tests"},
    Sensitivity:      schema.SensitivityLow,
})

// 2. After at least 2 successful episodes with the same tool pattern,
//    the next consolidation run creates a competence record automatically.
//    You can also trigger consolidation manually:
result, err := consolidationSvc.RunAll(ctx)
fmt.Printf("Competence records created: %d\n", result.CompetenceExtracted)

// 3. Retrieve competence records for a task
resp, _ := m.RetrieveGraph(ctx, &retrieval.RetrieveGraphRequest{
    TaskDescriptor: "fix build error",
    Trust: &retrieval.TrustContext{
        MaxSensitivity: schema.SensitivityMedium,
        Authenticated:  true,
    },
    MemoryTypes: []schema.MemoryType{
        schema.MemoryTypeCompetence,
    },
    RootLimit: 5,
    NodeLimit: 10,
    MaxHops:   0,
})

for _, node := range resp.Nodes {
    r := node.Record
    if p, ok := r.Payload.(*schema.CompetencePayload); ok {
        fmt.Printf("Skill: %s (success_rate=%.2f)\n",
            p.SkillName,
            p.Performance.SuccessRate,
        )
        for _, step := range p.Recipe {
            fmt.Printf("  - %s (tool: %s)\n", step.Step, step.Tool)
        }
    }
}

// 4. Reinforce the selected competence after a successful use
if len(resp.RootIDs) > 0 {
    m.Reinforce(ctx, resp.RootIDs[0], "build-agent", "procedure applied successfully")
}

```

--------------------------------

### Load Configuration from File

Source: https://membrane.gustycube.com/api/go/membrane

Reads a YAML configuration file and overlays its settings onto the `DefaultConfig`.

```go
func LoadConfig(path string) (*Config, error)

```

--------------------------------

### MembraneClient Initialization

Source: https://membrane.gustycube.com/sdks/python

Demonstrates how to initialize the MembraneClient with various options, including TLS and API key authentication. It also shows how to use the client as a context manager.

```APIDOC
## Client Options
```python
client = MembraneClient(
    "membrane.example.com:443",
    tls=True,
    tls_ca_cert="/path/to/ca.pem",
    api_key="your-api-key",
    timeout=10.0,
)
```

`addr`strdefault: localhost:9090
gRPC address of the Membrane daemon.
`tls`bool
Use TLS transport.
`tls_ca_cert`str
Optional CA certificate path. Supplying it implies TLS.
`api_key`str
Bearer token sent in gRPC metadata.
`timeout`float
Default timeout in seconds for RPC calls.
The client also supports the context-manager protocol:
```python
with MembraneClient("localhost:9090") as client:
    capture = client.capture_memory({"text": "Remember this"})
```
```

--------------------------------

### Install Python Dependencies for Vector Evals

Source: https://membrane.gustycube.com/guides/observability

Installs the necessary Python dependencies for running vector end-to-end evaluations.

```bash
python3 -m pip install -r tools/eval/requirements.txt  
```

--------------------------------

### RetrieveGraph gRPC Call Example

Source: https://membrane.gustycube.com/api/overview

This example demonstrates how to call the RetrieveGraph method on the Membrane gRPC service. It includes setting the authorization header for authentication and providing a sample request payload.

```APIDOC
## POST /membrane.v1.MembraneService/RetrieveGraph

### Description
Retrieves graph data based on the provided task descriptor, trust settings, memory types, and root limit.

### Method
POST

### Endpoint
`localhost:9090/membrane.v1.MembraneService/RetrieveGraph`

### Parameters
#### Request Body
- **task_descriptor** (string) - Required - A description of the task for which to retrieve graph data.
- **trust** (object) - Required - Trust settings for the retrieval.
  - **max_sensitivity** (string) - Optional - Maximum sensitivity level for trust.
  - **authenticated** (boolean) - Optional - Whether the request is authenticated.
- **memory_types** (array) - Required - A list of memory types to consider for retrieval.
- **root_limit** (integer) - Required - The maximum depth or number of root nodes to retrieve.

### Request Example
```json
{
  "task_descriptor": "fix build error",
  "trust": {
    "max_sensitivity": "medium",
    "authenticated": true
  },
  "memory_types": ["entity", "semantic", "competence"],
  "root_limit": 10
}
```

### Response
#### Success Response (200)
- **graph_nodes** (array) - Description of graph nodes returned.
- **graph_edges** (array) - Description of graph edges returned.
- **capture_responses** (array) - Description of capture responses.
- **retrieval_responses** (array) - Description of retrieval responses.

#### Response Example
```json
{
  "graph_nodes": [
    {
      "id": "node-1",
      "type": "entity",
      "properties": {
        "name": "example_node"
      }
    }
  ],
  "graph_edges": [
    {
      "source_node_id": "node-1",
      "target_node_id": "node-2",
      "type": "related_to",
      "properties": {}
    }
  ],
  "capture_responses": [],
  "retrieval_responses": []
}
```
```

--------------------------------

### grpcurl - GetMetrics

Source: https://membrane.gustycube.com/api/overview

Example of calling the GetMetrics gRPC method using grpcurl.

```APIDOC
## GetMetrics (grpcurl)

### Description
Calls the GetMetrics gRPC method to retrieve system metrics.

### Method
`POST`

### Endpoint
`membrane.v1.MembraneService/GetMetrics`

### Headers
- **authorization**: `Bearer your-key`

### Request Body
- (empty object `{}`)

### Request Example
```bash
grpcurl \
  -H 'authorization: Bearer your-key' \
  -d '{}' \
  -plaintext \
  localhost:9090 \
  membrane.v1.MembraneService/GetMetrics
```
```

--------------------------------

### Build Membrane Daemon Binary

Source: https://membrane.gustycube.com/guides/deployment

Clone the repository, navigate to the directory, and run 'make build' to compile the membraned binary. The executable will be placed in the ./bin/ directory.

```bash
git clone https://github.com/BennettSchwartz/membrane.git  
cd membrane  
make build  
```

--------------------------------

### grpcurl - CaptureMemory

Source: https://membrane.gustycube.com/api/overview

Example of calling the CaptureMemory gRPC method using grpcurl.

```APIDOC
## CaptureMemory (grpcurl)

### Description
Calls the CaptureMemory gRPC method to record a memory.

### Method
`POST`

### Endpoint
`membrane.v1.MembraneService/CaptureMemory`

### Headers
- **authorization**: `Bearer your-key`

### Request Body
- **source** (string) - Required - The source of the memory.
- **source_kind** (string) - Required - The kind of source for the memory.
- **content** (object) - Required - The content of the memory.
  - **ref** (string) - Required - Reference identifier for the content.
  - **text** (string) - Required - The textual content.
- **summary** (string) - Optional - A summary of the memory.
- **tags** (array[string]) - Optional - Tags associated with the memory.

### Request Example
```bash
grpcurl \
  -H 'authorization: Bearer your-key' \
  -d '{ \
    "source": "build-agent", \
    "source_kind": "event", \
    "content": { \
      "ref": "build#42", \
      "text": "Executed go build, failed with linker error" \
    }, \
    "summary": "Executed go build, failed with linker error", \
    "tags": ["build", "error"] \
  }' \
  -plaintext \
  localhost:9090 \
  membrane.v1.MembraneService/CaptureMemory
```
```

--------------------------------

### Start Membrane Daemon

Source: https://membrane.gustycube.com/sdks/openclaw-plugin

Ensure the Membrane daemon (`membraned`) is running and accessible at the configured gRPC endpoint.

```bash
./bin/membraned
```

--------------------------------

### Python Client - Capture Memory

Source: https://membrane.gustycube.com/api/overview

Example of capturing a memory candidate using the Python Membrane client.

```APIDOC
## Capture Memory (Python)

### Description
Captures a memory candidate with associated metadata.

### Method
`client.capture_memory()`

### Parameters
- **content** (dict) - Required - The content of the memory, including 'ref' and 'text'.
- **source_kind** (str) - Required - The kind of source for the memory (e.g., 'event').
- **summary** (str) - Optional - A brief summary of the memory.
- **tags** (list[str]) - Optional - A list of tags associated with the memory.

### Request Example
```python
client.capture_memory(
    {"ref": "task#1", "text": "Refactored auth middleware and verified package tests"},
    source_kind="event",
    summary="Refactored auth middleware",
    tags=["auth", "tests"],
)
```
```

--------------------------------

### Start Membrane

Source: https://membrane.gustycube.com/api/go/membrane

Begins background decay and consolidation schedulers. If embeddings are configured, it also backfills missing embeddings.

```APIDOC
## Start Membrane

### Description
Activates background schedulers for decay and consolidation, and initiates embedding backfilling if configured.

### Method
```go
func (m *Membrane) Start(ctx context.Context) error
```
```
Tokens:
Raw