Tools
Membrane
By A selective learning and memory substrate for agentic systems — typed, revisable, decayable memory with competence learning and trust-aware retrieval.
Install
npm install @gustycube/membraneConfiguration Example
db_path: "membrane.db"
listen_addr: ":9090"
decay_interval: "1h"
consolidation_interval: "6h"
default_sensitivity: "low"
selection_confidence_threshold: 0.7
# 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: 100README
# Membrane
[](https://github.com/GustyCube/membrane/actions/workflows/ci.yml)
[](https://goreportcard.com/report/github.com/GustyCube/membrane)
[](https://pkg.go.dev/github.com/GustyCube/membrane)
[](https://go.dev/)
[](LICENSE)
[](https://github.com/GustyCube/membrane/releases)
[](https://github.com/GustyCube/membrane/stargazers)
[](https://github.com/GustyCube/membrane/network/members)
[](https://github.com/GustyCube/membrane/issues)
[](https://github.com/GustyCube/membrane/pulls)
[](https://github.com/GustyCube/membrane/commits)
[](https://github.com/GustyCube/membrane/graphs/contributors)
**A general-purpose selective learning and memory substrate for LLM and agentic systems.**
Membrane gives long-lived LLM agents structured, revisable memory with built-in decay, trust-gated retrieval, and audit trails. Instead of an append-only context window or flat text log, agents get typed memory records that can be consolidated, revised, contested, and pruned over time.
---
## Table of Contents
- [Why Membrane](#why-membrane)
- [60-Second Mental Model](#60-second-mental-model)
- [Key Features](#key-features)
- [Memory Types](#memory-types)
- [Quick Start](#quick-start)
- [Architecture](#architecture)
- [Configuration](#configuration)
- [gRPC API](#grpc-api)
- [Revision Operations](#revision-operations)
- [Evaluation and Metrics](#evaluation-and-metrics)
- [Observability](#observability)
- [TypeScript Client](#typescript-client)
- [LLM Integration Pattern](#llm-integration-pattern)
- [Python Client](#python-client)
- [Documentation](#documentation)
- [Contributing](#contributing)
- [Star History](#star-history)
- [License](#license)
---
## Why Membrane
Most LLM/agent "memory" is either ephemeral (context windows that reset each turn) or an append-only text log stuffed into a RAG pipeline. That gives you retrieval, but not learning: facts get stale, procedures drift, and the system cannot revise itself safely.
Membrane makes memory **selective** and **revisable**. It captures raw experience, promotes it into structured knowledge, and lets you supersede, fork, contest, or retract that knowledge with evidence. The result is an agent that can improve over time while remaining predictable, auditable, and safe.
## 60-Second Mental Model
1. **Ingest** events, tool outputs, observations, and working state.
2. **Consolidate** episodic traces into semantic facts, competence records, and plan graphs.
3. **Retrieve** in layers with trust gating and salience ranking.
4. **Revise** knowledge with explicit operations and audit trails.
5. **Decay** salience over time unless reinforced by success.
## Key Features
- **Typed Memory** -- Explicit schemas and lifecycles for each memory type, not a flat text store.
- **Revisable Knowledge** -- Supersede, fork, retract, merge, and contest records with full provenance tracking.
- **Competence Learning** -- Agents learn *how* to solve problems (procedures, success rates), not just *what* happened.
- **Decay and Consolidation** -- Time-based salience decay keeps memory useful; background consolidation extracts durable knowledge from episodic traces.
- **Trust-Aware Retrieval** -- Sensitivity levels (public, low, medium, high, hyper) with graduated access control and redacted responses for records above the caller's trust level.
- **Security and Operations** -- SQLCipher encryption at rest, optional TLS and API key authentication, configurable rate limiting, full audit logs.
- **Observability** -- Built-in metrics for retrieval usefulness, competence success rate, plan reuse frequency, memory growth, and revision rate.
- **gRPC API** -- 15-method gRPC service with TypeScript and Python client SDKs, or use Membrane as an embedded Go library.
- **LLM-Ready Context Retrieval** -- Retrieve trust-filtered, typed memory and inject it directly into LLM prompts for planning, execution, and self-correction loops.
## Memory Types
| Type | Purpose | Example |
|------|---------|---------|
| **Episodic** | Raw experience capture (immutable) | Tool calls, errors, observations from a debugging session |
| **Working** | Current task state | "Backend initialized, frontend pending, docs TODO" |
| **Semantic** | Stable facts and preferences | "User prefers Go for backend services" |
| **Competence** | Learned procedures with success tracking | "To fix linker cache error: clear cache, rebuild with flags" |
| **Plan Graph** | Reusable solution structures as directed graphs | Multi-step project setup workflow with dependencies and checkpoints |
Each memory type has its own schema, lifecycle rules, and consolidation behavior. Episodic records are immutable once ingested. Working memory tracks in-flight task state. Semantic, competence, and plan graph records are the durable output of consolidation and can be revised through explicit operations.
## Quick Start
### Prerequisites
- Go 1.22 or later
- Make
- Protocol Buffers compiler (`protoc` >= 3.20) for gRPC development
- Node.js 20+ for the TypeScript client SDK
- Python 3.10+ for the Python client SDK
### Build and Run
```bash
git clone https://github.com/GustyCube/membrane.git
cd membrane
# Build the daemon
make build
# Run tests
make test
# Start with default SQLite storage
./bin/membraned
# With custom configuration
./bin/membraned --config /path/to/config.yaml
# Override database path or listen address
./bin/membraned --db /path/to/membrane.db --addr :8080
```
### Using the Go Library
Membrane can be used as an embedded library without running the daemon:
```go
package main
import (
"context"
"fmt"
"log"
"github.com/GustyCube/membrane/pkg/ingestion"
"github.com/GustyCube/membrane/pkg/membrane"
"github.com/GustyCube/membrane/pkg/retrieval"
"github.com/GustyCube/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()
m.Start(ctx)
// Ingest an episodic event (tool call observation)
rec, _ := m.IngestEvent(ctx, ingestion.IngestEventRequest{
Source: "build-agent",
EventKind: "tool_call",
Ref: "build#42",
Summary: "Executed go build, failed with linker error",
Tags: []string{"build", "error"},
})
fmt.Printf("Ingested episodic record: %s\n", rec.ID)
// Ingest a semantic observation
m.IngestObservation(ctx, ingestion.IngestObservationRequest{
Source: "build-agent",
Subject: "user",
Predicate: "prefers_language",
Object: "go",
Tags: []string{"preferences"},
})
// Ingest working memory state
m.IngestWorkingState(ctx, ingestion.IngestWorkingStateRequest{
Source: "build-agent",
ThreadID: "session-001",
State: schema.TaskStateExecuting,
NextActions: []string{"run tests", "deploy"},
})
// Retrieve with trust context
resp, _ := 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)
}
}
```
## Architecture
Membrane runs as a long-lived daemon or embedded library. The architecture is organized into three logical planes:
```
+------------------+ +------------------+ +----------------------+
| Ingestion Plane |---->| Policy Plane |---->| Storage & Retrieval |
+------------------+ +------------------+ +----------------------+
| | |
Events, tool Classification, SQLCipher (encrypted),
outputs, obs., sensitivity, audit trails,
working state decay profiles trust-gated access
```
### Storage Model
- **Authoritative Store** -- SQLCipher-encrypted SQLite database for metadata, lifecycle state, revision chains, relations, and audit history.
- **Structured Payloads** -- Type-specific schemas stored as JSON within the authoritative store.
- **Relationship Graph** -- Relations between records (supersedes, derived_from, contested_by, supports, contradicts) stored alongside the records they describe.
### Background Jobs
| Job | Default Interval | Purpose |
|-----|-----------------|---------|
| **Decay** | 1 hour | Applies time-based salience decay using exponential or linear curves |
| **Pruning** | With decay | Deletes records with `auto_prune` policy whose salience has reached 0 |
| **Consolidation** | 6 hours | Extracts semantic facts, competence records, and plan graphs from episodic memory |
### Security Model
... (truncated)
tools
Comments
Sign in to leave a comment