Membrane

Memory that agents can connect, revise, and learn from.

Documentation · Quickstart · Architecture · API reference

Membrane gives LLM agents persistent, structured memory. An agent can remember what happened, connect it to existing knowledge, retrieve the context a task needs, and correct that knowledge when circumstances change.

Use it for agents that carry work across sessions, maintain changing facts, reuse successful procedures, or need to explain which memories informed an answer.

What changes when an agent has memory?

Context stays connected. Facts, episodes, procedures, and plans link through shared entities. Retrieval returns a bounded graph of relevant records.
Knowledge can be corrected. Supersede stale facts, contest uncertain claims, fork alternatives, or retract a record while retaining its audit history.
Experience influences future work. Reinforcement, decay, and consolidation change what gets remembered and retrieved over time.
Access follows policy. Scope and sensitivity rules govern reads and writes; restricted responses omit or redact information the caller cannot access.

How it fits together

flowchart LR
    Experience["Events, observations<br/>and task state"] --> Memory["Typed memory<br/>+ entity links"]
    Memory --> Context["Relevant context<br/>within access limits"]
    Context --> Agent["Agent acts"]
    Agent -->|"New evidence and outcomes"| Memory

Five memory layers, connected by entities:

Memory	The question it answers	Example
Episodic	What happened?	An incident, a tool result, an observation
Working	What are we doing now?	The current goal, next action, open questions
Semantic	What do we know?	A preference, a system fact, a relationship
Competence	What has worked before?	A debugging procedure and its success history
Plan graph	How should this work unfold?	A rollout with dependencies and checkpoints
Entity	What is this about?	The same service, project, file, or person across memories

Explore the memory model →

Choose your integration

Use Membrane from…	Connection	Start here
Go	Embed the library in your process	Go guide · Package reference
TypeScript / JavaScript	Connect to the gRPC daemon	SDK and examples
Python	Connect to the gRPC daemon	SDK and examples
OpenClaw	Add memory tools and context through the plugin	Plugin setup
Another language	Use the protobuf service contract	gRPC API

For a complete agent loop, see the agent harness. It exercises capture, graph retrieval, revisions, and access controls against a running daemon, with both deterministic and optional live-model scenarios.

Run it locally

[!IMPORTANT] PostgreSQL with pgvector is required, whether you embed the Go library or run the daemon. Embedding and LLM providers are optional: structured capture, graph retrieval, revisions, and access controls work without a model API key.

Build and start the daemon — Go, Docker Compose, and Make

Use the Go toolchain declared in go.mod. From a fresh checkout:

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

export MEMBRANE_POSTGRES_PASSWORD="$(openssl rand -hex 24)"
export MEMBRANE_POSTGRES_DSN="postgres://membrane:${MEMBRANE_POSTGRES_PASSWORD}@127.0.0.1:5432/membrane_test?sslmode=disable"
docker compose up -d
until docker compose exec -T postgres pg_isready -U membrane -d membrane_test; do sleep 1; done
./bin/membraned --postgres-dsn "$MEMBRANE_POSTGRES_DSN"

The daemon applies its database schema on startup and listens on 127.0.0.1:9090. Its default policy permits the default scope at LOW sensitivity. See configuration for scopes, provider settings, TLS, and authentication.

The TypeScript and Python quickstarts connect to this daemon.

Add capabilities as you need them

Setup	What it enables
PostgreSQL + pgvector	Typed records, entity links, bounded retrieval, revisions, and salience
+ Embedding provider	Automatic vector population and hybrid vector/salience ranking
+ LLM provider	Optional interpretation during capture and semantic extraction during consolidation

Full quickstart · Deployment guide · Security guide

Explore the project

I want to…	Read
Understand the design	Architecture · Specification
Configure a deployment	Configuration · Deployment
Understand retrieval and revision	Retrieval · Revision
Inspect behavior and limitations	Observability · Trust and sensitivity
Change the code	Contributing · Core packages · Integration and evaluation tests

Development and verification

Go uses the toolchain in go.mod. The TypeScript SDK and examples need Node.js 20.19+, the docs toolchain needs Node.js 22+, and the Python SDK needs Python 3.10+.

Command	What it checks
`make build`	Build the daemon
`make test`	Run Go tests
`make verify`	Check storage/protobuf/package contracts, SDKs, harness tools, and the docs build
`make lint`	Run Go vet and Staticcheck
`make agent-harness-deterministic`	Exercise an agent scenario against PostgreSQL

Set disposable PostgreSQL DSNs to include database integration tests. Provider credentials enable live embedding and model evaluations. See CONTRIBUTING.md and the harness guide.

Contributing

Bug reports, integration feedback, and contributions are welcome. Open an issue or read the contribution guide.

MIT licensed. See LICENSE.

membrane

Links

README