Skip to content
Back to search

membrane

A selective learning and memory substrate for agentic systems — typed, revisable, decayable memory with competence learning and trust-aware retrieval.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/bennettschwartz--membrane/badge.svg)](/listings/bennettschwartz--membrane)

HTML

<a href="/listings/bennettschwartz--membrane"><img src="/api/listings/bennettschwartz--membrane/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 158 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <img src="static/img/logo-mark.svg" width="72" height="72" alt="Membrane logo">
  3. </p>
  4. <h1 align="center">Membrane</h1>
  5. <p align="center">
  6. <strong>Memory that agents can connect, revise, and learn from.</strong>
  7. </p>
  8. <p align="center">
  9. <a href="https://membrane.gustycube.com">Documentation</a> ·
  10. <a href="https://membrane.gustycube.com/quickstart">Quickstart</a> ·
  11. <a href="https://membrane.gustycube.com/architecture">Architecture</a> ·
  12. <a href="https://membrane.gustycube.com/api/overview">API reference</a>
  13. </p>
  14. [![CI](https://github.com/BennettSchwartz/membrane/actions/workflows/ci.yml/badge.svg)](https://github.com/BennettSchwartz/membrane/actions/workflows/ci.yml)
  15. [![Go Reference](https://pkg.go.dev/badge/github.com/BennettSchwartz/membrane.svg)](https://pkg.go.dev/github.com/BennettSchwartz/membrane)
  16. [![License: MIT](https://img.shields.io/github/license/BennettSchwartz/membrane)](LICENSE)
  17. Membrane gives LLM agents persistent, structured memory. An agent can remember
  18. what happened, connect it to existing knowledge, retrieve the context a task
  19. needs, and correct that knowledge when circumstances change.
  20. Use it for agents that carry work across sessions, maintain changing facts,
  21. reuse successful procedures, or need to explain which memories informed an answer.
  22. ## What changes when an agent has memory?
  23. - **Context stays connected.** Facts, episodes, procedures, and plans link through
  24. shared entities. Retrieval returns a bounded graph of relevant records.
  25. - **Knowledge can be corrected.** Supersede stale facts, contest uncertain claims,
  26. fork alternatives, or retract a record while retaining its audit history.
  27. - **Experience influences future work.** Reinforcement, decay, and consolidation
  28. change what gets remembered and retrieved over time.
  29. - **Access follows policy.** Scope and sensitivity rules govern reads and writes;
  30. restricted responses omit or redact information the caller cannot access.
  31. ## How it fits together
  32. ```mermaid
  33. flowchart LR
  34. Experience["Events, observations<br/>and task state"] --> Memory["Typed memory<br/>+ entity links"]
  35. Memory --> Context["Relevant context<br/>within access limits"]
  36. Context --> Agent["Agent acts"]
  37. Agent -->|"New evidence and outcomes"| Memory
  38. ```
  39. **Five memory layers, connected by entities:**
  40. | Memory | The question it answers | Example |
  41. | :--- | :--- | :--- |
  42. | **Episodic** | What happened? | An incident, a tool result, an observation |
  43. | **Working** | What are we doing now? | The current goal, next action, open questions |
  44. | **Semantic** | What do we know? | A preference, a system fact, a relationship |
  45. | **Competence** | What has worked before? | A debugging procedure and its success history |
  46. | **Plan graph** | How should this work unfold? | A rollout with dependencies and checkpoints |
  47. | **Entity** | What is this about? | The same service, project, file, or person across memories |
  48. [Explore the memory model →](docs/concepts/memory-types.mdx)
  49. ## Choose your integration
  50. | Use Membrane from… | Connection | Start here |
  51. | :--- | :--- | :--- |
  52. | **Go** | Embed the library in your process | [Go guide](docs/guides/go-library.mdx) · [Package reference](https://pkg.go.dev/github.com/BennettSchwartz/membrane/pkg/membrane) |
  53. | **TypeScript / JavaScript** | Connect to the gRPC daemon | [SDK and examples](clients/typescript/README.md) |
  54. | **Python** | Connect to the gRPC daemon | [SDK and examples](clients/python/README.md) |
  55. | **OpenClaw** | Add memory tools and context through the plugin | [Plugin setup](clients/openclaw/README.md) |
  56. | **Another language** | Use the protobuf service contract | [gRPC API](api/proto/membrane/v1/membrane.proto) |
  57. For a complete agent loop, see the [agent harness](examples/agent-harness/README.md).
  58. It exercises capture, graph retrieval, revisions, and access controls against a
  59. running daemon, with both deterministic and optional live-model scenarios.
  60. ## Run it locally
  61. > [!IMPORTANT]
  62. > **PostgreSQL with pgvector is required**, whether you embed the Go library or
  63. > run the daemon. Embedding and LLM providers are optional: structured capture,
  64. > graph retrieval, revisions, and access controls work without a model API key.
  65. <details>
  66. <summary><strong>Build and start the daemon</strong> — Go, Docker Compose, and Make</summary>
  67. Use the Go toolchain declared in [go.mod](go.mod). From a fresh checkout:
  68. ```bash
  69. git clone https://github.com/BennettSchwartz/membrane.git
  70. cd membrane
  71. make build
  72. export MEMBRANE_POSTGRES_PASSWORD="$(openssl rand -hex 24)"
  73. export MEMBRANE_POSTGRES_DSN="postgres://membrane:${MEMBRANE_POSTGRES_PASSWORD}@127.0.0.1:5432/membrane_test?sslmode=disable"
  74. docker compose up -d
  75. until docker compose exec -T postgres pg_isready -U membrane -d membrane_test; do sleep 1; done
  76. ./bin/membraned --postgres-dsn "$MEMBRANE_POSTGRES_DSN"
  77. ```
  78. The daemon applies its database schema on startup and listens on
  79. `127.0.0.1:9090`. Its default policy permits the `default` scope at LOW sensitivity.
  80. See [configuration](docs/guides/configuration.mdx) for scopes, provider settings,
  81. TLS, and authentication.
  82. The [TypeScript](clients/typescript/README.md#quick-start) and
  83. [Python](clients/python/README.md#quick-start) quickstarts connect to this daemon.
  84. </details>
  85. ### Add capabilities as you need them
  86. | Setup | What it enables |
  87. | :--- | :--- |
  88. | **PostgreSQL + pgvector** | Typed records, entity links, bounded retrieval, revisions, and salience |
  89. | **+ Embedding provider** | Automatic vector population and hybrid vector/salience ranking |
  90. | **+ LLM provider** | Optional interpretation during capture and semantic extraction during consolidation |
  91. [Full quickstart](docs/quickstart.mdx) · [Deployment guide](docs/guides/deployment.mdx) · [Security guide](docs/guides/security.mdx)
  92. ## Explore the project
  93. | I want to… | Read |
  94. | :--- | :--- |
  95. | Understand the design | [Architecture](docs/architecture.mdx) · [Specification](rfc.md) |
  96. | Configure a deployment | [Configuration](docs/guides/configuration.mdx) · [Deployment](docs/guides/deployment.mdx) |
  97. | Understand retrieval and revision | [Retrieval](docs/api/retrieval.mdx) · [Revision](docs/api/revision.mdx) |
  98. | Inspect behavior and limitations | [Observability](docs/guides/observability.mdx) · [Trust and sensitivity](docs/concepts/trust-and-sensitivity.mdx) |
  99. | Change the code | [Contributing](CONTRIBUTING.md) · [Core packages](pkg) · [Integration and evaluation tests](tests) |
  100. <details>
  101. <summary><strong>Development and verification</strong></summary>
  102. Go uses the toolchain in [go.mod](go.mod). The TypeScript SDK and examples need
  103. Node.js 20.19+, the docs toolchain needs Node.js 22+, and the Python SDK needs
  104. Python 3.10+.
  105. | Command | What it checks |
  106. | :--- | :--- |
  107. | `make build` | Build the daemon |
  108. | `make test` | Run Go tests |
  109. | `make verify` | Check storage/protobuf/package contracts, SDKs, harness tools, and the docs build |
  110. | `make lint` | Run Go vet and Staticcheck |
  111. | `make agent-harness-deterministic` | Exercise an agent scenario against PostgreSQL |
  112. Set disposable PostgreSQL DSNs to include database integration tests. Provider
  113. credentials enable live embedding and model evaluations. See
  114. [CONTRIBUTING.md](CONTRIBUTING.md) and the [harness guide](examples/agent-harness/README.md).
  115. </details>
  116. ## Contributing
  117. Bug reports, integration feedback, and contributions are welcome.
  118. [Open an issue](https://github.com/BennettSchwartz/membrane/issues) or read the
  119. [contribution guide](CONTRIBUTING.md).
  120. **MIT licensed.** See [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.