Membrane是什么？2026年智能体系统选择性学习与记忆框架详解

一个为LLM和智能体系统设计的通用选择性学习与记忆基板。

A general-purpose selective learning and memory substrate for LLM and agentic systems.

Membrane为长生命周期的LLM智能体提供了结构化、可修订、内置衰减、基于信任门控检索和审计追踪的记忆能力。它摒弃了仅追加的上下文窗口或扁平文本日志，转而提供类型化的记忆记录，这些记录可以随着时间推移进行整合、修订、质疑和修剪。

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.

---

目录

• 为何选择 Membrane
• 60秒心智模型
• 核心特性
• 记忆类型
• 快速开始
• 架构
• 配置
• gRPC API

---

为何选择 Membrane

大多数LLM/智能体的“记忆”要么是短暂的（每次对话重置的上下文窗口），要么是塞入RAG管道的仅追加文本日志。这提供了检索功能，但没有学习能力：事实会过时，流程会漂移，系统无法安全地自我修正。

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使记忆变得可选择和可修订。它捕获原始经验，将其提升为结构化知识，并允许你基于证据来取代、分叉、质疑或撤回这些知识。其结果是，智能体能够随时间推移不断改进，同时保持可预测性、可审计性和安全性。

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秒心智模型

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.

核心特性

• 类型化记忆 -- 每种记忆类型都有明确的模式和生命周期，而非扁平的文本存储。

  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 semantic facts, competence records, and plan graphs from episodic traces.

• 基于LLM的语义提取 -- 在Postgres + LLM层级，情景记录可以通过结构化提取管道异步转换为类型化的语义事实。

  LLM-Based Semantic Extraction -- On the Postgres + LLM tier, episodic records can be converted into typed semantic facts asynchronously through a structured extraction pipeline.

• 信任感知检索 -- 具有分级访问控制的敏感度级别（公开、低、中、高、极高），对于超出调用者信任级别的记录返回脱敏响应。

  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.

• 安全与运维 -- SQLCipher静态加密，可选的TLS和API密钥认证，可配置的速率限制，完整的审计日志。

  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个方法的gRPC服务，提供TypeScript和Python客户端SDK，也可将Membrane作为嵌入式Go库使用。

  gRPC API -- 15-method gRPC service with TypeScript and Python client SDKs, or use Membrane as an embedded Go library.

• 向量感知检索 -- 启用Postgres + pgvector后端后，能力和计划图的适用性可以通过嵌入相似度来评分，而不仅仅是依赖置信度回退机制。

  Vector-Aware Retrieval -- With the Postgres + pgvector backend enabled, competence and plan-graph applicability can be scored with embedding similarity instead of the confidence-only fallback.

• LLM就绪的上下文检索 -- 检索经过信任过滤的类型化记忆，并直接注入到LLM提示中，用于规划、执行、自我纠正和后台学习循环。

  LLM-Ready Context Retrieval -- Retrieve trust-filtered, typed memory and inject it directly into LLM prompts for planning, execution, self-correction, and background learning loops.

记忆类型

类型	目的	示例
情景记忆	原始经验捕获（不可变）	工具调用、错误、调试会话中的观察结果
工作记忆	当前任务状态	"后端已初始化，前端待处理，文档待办"
语义记忆	稳定的事实和偏好	"用户偏好使用Go进行后端服务开发"
能力记忆	带有成功率追踪的学习流程	"修复链接器缓存错误：清除缓存，使用标志重新构建"
计划图	作为有向图的可复用解决方案结构	包含依赖项和检查点的多步骤项目设置工作流

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.

快速开始

先决条件

• Go 1.22 或更高版本

  Go 1.22 or later

• Make

  Make

• Protocol Buffers 编译器 (protoc >= 3.20) 用于 gRPC 开发

  Protocol Buffers compiler (protoc>= 3.20) for gRPC development

• Node.js 20+ 用于 TypeScript 客户端 SDK

  Node.js 20+ for the TypeScript client SDK

• Python 3.10+ 用于 Python 客户端 SDK

  Python 3.10+ for the Python client SDK

构建与运行

git clone https://github.com/GustyCube/membrane.git
cd membrane

# 构建守护进程
make build

# 运行测试
make test

# 使用默认 SQLite 存储启动
./bin/membraned

# 使用 Postgres + pgvector 启动
./bin/membraned --postgres-dsn postgres://membrane:membrane@localhost:5432/membrane_test?sslmode=disable

# 使用自定义配置
./bin/membraned --config /path/to/config.yaml

# 覆盖数据库路径或监听地址
./bin/membraned --db /path/to/membrane.db --addr :8080

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

# Start with Postgres + pgvector instead
./bin/membraned --postgres-dsn postgres://membrane:membrane@localhost:5432/membrane_test?sslmode=disable

# 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

使用 Go 库

Membrane 可以作为嵌入式库使用，无需运行守护进程：

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)

    // 摄取一个情景事件（工具调用观察）
    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)

    // 摄取一个语义观察
    m.IngestObservation(ctx, ingestion.IngestObservationRequest{
        Source:    "build-agent",
        Subject:   "user",
        Predicate: "prefers_language",
        Object:    "go",
        Tags:      []string{"preferences"},
    })

    // 摄取工作记忆状态
    m.IngestWorkingState(ctx, ingestion.IngestWorkingStateRequest{
        Source:     "build-agent",
        ThreadID:   "session-001",
        State:      schema.TaskStateExecuting,
        NextActions: []string{"run tests", "deploy"},
    })

    // 在信任上下文中检索
    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)
    }
}

Membrane can be used as an embedded library without running the daemon:
(Code example remains the same in English)

架构

Membrane 可以作为长生命周期守护进程或嵌入式库运行。其架构组织为三个逻辑平面：

+------------------+     +------------------+     +----------------------+
|  摄取平面        |---->|  策略平面        |---->|  存储与检索平面      |
+------------------+     +------------------+     +----------------------+
        |                        |                         |
   事件、工具输出、       分类、敏感度、           SQLCipher（加密）、
   观察、工作状态         衰减配置文件            审计追踪、信任门控访问

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

存储模型

• 权威存储 -- 带有 SQLCipher 的 SQLite 仍然是默认的嵌入式存储；Postgres + pgvector 可作为可选后端，用于并发部署和基于嵌入的检索。

  Authoritative Store -- SQLite with SQLCipher remains the default embedded store; Postgres + pgvector is available as an opt-in backend for concurrent deployments and embedding-backed retrieval.

• 结构化负载 -- 类型特定的模式以 JSON 格式存储在权威存储中。

  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.

部署层级

层级	后端	嵌入	LLM	行为
1	SQLite	-	-	零基础设施默认设置，基于置信度的适用性回退
2	Postgres	-	-	并发写入器，JSONB存储，检索语义与层级1相同
3	Postgres + pgvector	是	-	推荐：所有记录类型的混合向量+显著性排序
4	Postgres + pgvector	是	是	完整系统，具有基于LLM的情景到语义提取

Tier	Backend	Embedding	LLM	Behavior
1	SQLite	-	-	Zero-infra default, confidence-based applicability fallback
2	Postgres	-	-	Concurrent writers, JSONB storage, same retrieval semantics as tier 1
3	Postgres + pgvector	Yes	-	Recommended: hybrid vector+salience ranking for all record types
4	Postgres + pgvector	Yes	Yes	Full system with LLM-backed episodic to semantic extraction

后台作业

作业	默认间隔	目的

常见问题（FAQ）

Membrane与传统RAG的记忆管理有何不同？

Membrane提供结构化、可修订的记忆，具备内置衰减和信任门控检索，而传统RAG通常依赖仅追加的文本日志，缺乏学习能力和安全修订机制。

如何开始使用Membrane构建智能体系统？

参考快速开始章节，确保满足先决条件后，按照构建与运行步骤操作。Membrane提供类型化记忆记录和gRPC API，支持智能体的选择性学习与记忆管理。

Membrane如何确保智能体的安全性和可审计性？

通过信任门控检索、审计追踪和可修订知识功能，Membrane允许基于证据取代、分叉或撤回记录，确保智能体改进的同时保持可预测和可审计。