@vainplex/openclaw-membrane 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+## [0.3.0] — 2026-02-23
+
+### Added
+- `membrane_search` tool — gRPC Retrieve with client-side filtering, prioritizes user/assistant messages
+- `before_agent_start` hook — auto-injects `<membrane-context>` into system prompt
+- `parser.ts` — shared record parser for all 4 Membrane memory types (episodic, semantic, competence, working)
+- `types.ts` — full TypeScript interfaces (PluginApi, PluginConfig, MembraneRecord, etc.)
+- `validateConfig()` — typed config extraction (rejects wrong types)
+- `maxRetries` cap (10) on reliability buffer — prevents infinite retry loops
+- 44 tests across 4 files (parser, mapping, buffer, config)
+
+### Changed
+- `register()` refactored from 277 lines to 38 (split into 7 focused functions)
+- `mapEvent()` refactored from 82 lines to 10 (6 individual mappers)
+- Zero `any` remaining (was 18)
+- Logger passed to ReliabilityManager (was `console.error`)
+- All catches log with `logger.debug/warn` (was silent `catch {}`)
+
+### Removed
+- Hardcoded API key fallback — auth via `MEMBRANE_API_KEY` env only
+- Module-level mutable state — now closure-scoped in `register()`
+
+### Security
+- Removed `'anothersecretapi456'` hardcoded credential from client.ts
+
+## [0.1.0] — 2026-02-23
+
+### Added
+- Initial plugin: event ingestion via gRPC IngestEvent
+- Ring buffer with retry logic and exponential backoff
+- Event mapping for 6 OpenClaw event types
+- Sensitivity mapping with secure fallback

package/README.md

@@ -0,0 +1,257 @@
+# @vainplex/openclaw-membrane
+
+Membrane gRPC bridge for OpenClaw — persistent episodic memory via [GustyCube/membrane](https://github.com/GustyCube/membrane) sidecar.
+
+**What it does:** Every conversation, tool call, and decision flows into Membrane's biological memory model. Memories decay over time. Frequently accessed ones grow stronger. Your agent remembers what matters and forgets what doesn't.
+
+## Quick Start
+
+### 1. Run Membrane sidecar
+
+```bash
+# Docker (recommended)
+docker run -d --name membrane \
+  -p 50051:50051 \
+  -v membrane-data:/data \
+  openclaw-membrane:local \
+  membraned -config /app/config.yaml
+
+# Or use docker-compose (see below)
+```
+
+<details>
+<summary>docker-compose.yml</summary>
+
+```yaml
+services:
+  membrane:
+    image: openclaw-membrane:local
+    container_name: membrane
+    ports:
+      - "50051:50051"
+    volumes:
+      - ./data:/data:rw
+      - ./config.yaml:/app/config.yaml:ro
+    entrypoint: ["membraned", "-config", "/app/config.yaml"]
+    restart: unless-stopped
+```
+
+Minimal `config.yaml`:
+```yaml
+listen_addr: ":50051"
+db_path: "/data/membrane.db"
+storage_backend: "sqlite"
+log_level: "info"
+```
+</details>
+
+### 2. Install the plugin
+
+```bash
+# From npm
+cd ~/.openclaw/extensions
+mkdir openclaw-membrane && cd openclaw-membrane
+npm install @vainplex/openclaw-membrane
+
+# Or from source
+git clone https://github.com/alberthild/openclaw-membrane.git
+cd openclaw-membrane
+npm install && npx tsc
+cp -r dist/ ~/.openclaw/extensions/openclaw-membrane/dist/
+cp openclaw.plugin.json package.json ~/.openclaw/extensions/openclaw-membrane/
+cd ~/.openclaw/extensions/openclaw-membrane && npm install --production
+```
+
+### 3. Enable in OpenClaw
+
+Add to your `openclaw.json`:
+```json
+{
+  "plugins": {
+    "entries": {
+      "openclaw-membrane": {
+        "enabled": true,
+        "config": {
+          "grpc_endpoint": "localhost:50051"
+        }
+      }
+    }
+  }
+}
+```
+
+### 4. Restart gateway
+
+```bash
+openclaw doctor --fix
+openclaw gateway restart
+```
+
+### 5. Verify
+
+Check gateway logs for:
+```
+[membrane] Registered bridge to localhost:50051
+```
+
+Send a message — it should appear as a Membrane record. Use the `membrane_search` tool to query:
+```
+membrane_search("what did we discuss yesterday")
+```
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| **Event Ingestion** | Writes messages, tool calls, facts, and outcomes to Membrane via gRPC |
+| **`membrane_search` Tool** | LLM-callable search — each query boosts salience of matched records (rehearsal) |
+| **Auto-Context** | `before_agent_start` hook injects `<membrane-context>` into the system prompt |
+| **Reliability Buffer** | Ring buffer with exponential backoff, max 10 retries, graceful shutdown flush |
+| **4 Memory Types** | Parses episodic (timeline), semantic (SPO facts), competence (patterns), working (state) |
+
+## How it works
+
+```
+                         WRITE PATH
+OpenClaw Events ──→ mapping.ts ──→ buffer.ts ──→ gRPC IngestEvent ──→ Membrane DB
+                                                                          │
+                         READ PATH                                        │
+User Prompt ──→ before_agent_start hook ──→ gRPC Retrieve ──→ parser.ts ──┘
+                                                    │
+                                              <membrane-context>
+                                            injected into prompt
+                         
+                         SEARCH PATH
+LLM calls membrane_search ──→ gRPC Retrieve ──→ parser.ts ──→ formatted results
+                                    │
+                              salience boosted
+                             (rehearsal effect)
+```
+
+**Write path:** Every OpenClaw event (message in/out, tool call, fact extraction, task outcome) is mapped to a Membrane gRPC call and queued in a ring buffer. Failed calls retry with exponential backoff.
+
+**Read path:** Before each agent turn, the plugin calls Membrane's Retrieve with the user prompt. Matching records are parsed, filtered (prioritizing user/assistant messages over tool calls), and injected as `<membrane-context>`.
+
+**Search path:** The `membrane_search` tool lets the LLM explicitly query Membrane. Each Retrieve call triggers Membrane's rehearsal mechanism — accessed memories gain salience and resist decay.
+
+## Event Mapping
+
+| OpenClaw Event | Membrane Method | Memory Kind |
+|---------------|----------------|-------------|
+| `message_received` | IngestEvent | user_message |
+| `message_sent` | IngestEvent | assistant_message |
+| `session_start` | IngestEvent | session_init |
+| `after_tool_call` | IngestToolOutput | tool_call |
+| `fact_extracted` | IngestObservation | semantic |
+| `task_completed` | IngestOutcome | outcome |
+
+## Configuration
+
+### External Config (recommended)
+
+Create `~/.openclaw/plugins/openclaw-membrane/config.json`:
+
+```json
+{
+  "grpc_endpoint": "localhost:50051",
+  "buffer_size": 1000,
+  "default_sensitivity": "low",
+  "retrieve_enabled": true,
+  "retrieve_limit": 5,
+  "retrieve_min_salience": 0.1,
+  "retrieve_max_sensitivity": "medium",
+  "retrieve_timeout_ms": 10000
+}
+```
+
+### Config Reference
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `grpc_endpoint` | string | `localhost:50051` | Membrane gRPC address |
+| `buffer_size` | number | `1000` | Ring buffer capacity |
+| `default_sensitivity` | string | `low` | Default event sensitivity (`public`/`low`/`medium`/`high`/`hyper`) |
+| `retrieve_enabled` | boolean | `true` | Enable auto-context injection |
+| `retrieve_limit` | number | `5` | Max memories per turn |
+| `retrieve_min_salience` | number | `0.1` | Min salience for Retrieve |
+| `retrieve_max_sensitivity` | string | `medium` | Max sensitivity for Retrieve |
+| `retrieve_timeout_ms` | number | `2000` | Retrieve timeout in ms |
+
+### Sensitivity Model
+
+Events are classified by sensitivity based on context:
+
+| Condition | Sensitivity |
+|-----------|------------|
+| Credential/auth events | `hyper` |
+| DM / private channel | `medium` |
+| Tool calls | `medium` |
+| Default | config value (`low`) |
+| Invalid/unknown | `hyper` (secure fallback) |
+
+### Authentication
+
+Set `MEMBRANE_API_KEY` environment variable if your Membrane instance requires auth.
+
+## Architecture
+
+```
+openclaw-membrane/
+├── index.ts        # Plugin entry: wiring, tool + hook registration (248 LOC)
+├── types.ts        # TypeScript interfaces, config defaults (132 LOC)
+├── parser.ts       # Shared record parser, all 4 memory types (136 LOC)
+├── mapping.ts      # Event → gRPC payload mapping, 6 types (151 LOC)
+├── buffer.ts       # Ring buffer + reliability manager (120 LOC)
+├── client.ts       # gRPC client wrapper (71 LOC)
+├── test/
+│   ├── parser.test.ts    # 15 tests
+│   ├── mapping.test.ts   # 15 tests
+│   ├── buffer.test.ts    # 6 tests
+│   └── config.test.ts    # 8 tests
+└── assets/proto/         # Membrane gRPC proto definitions
+```
+
+**Total:** 858 LOC source, 44 tests, 0 `any`.
+
+## Tests
+
+```bash
+npx vitest run        # Run all 44 tests
+npx vitest --watch    # Watch mode
+```
+
+## Known Limitations
+
+**Be honest about what this can and can't do today:**
+
+- **No fulltext search.** Membrane's Retrieve ranks by salience/recency/decay, not text content. If you search for "pipeline", it won't find records containing "pipeline" — it returns whatever has highest salience. This gets better over time as rehearsal boosts relevant records, but early on results can feel random.
+- **Backfilled records don't benefit from decay.** If you bulk-import history, all records start with identical salience and no access history. Membrane's biological memory model needs organic growth — records written through real conversations develop natural salience patterns.
+- **Single memory slot in OpenClaw.** The `before_agent_start` hook only fires for the active memory plugin. If you use `memory-lancedb` (default), Membrane's auto-context injection won't fire. The `membrane_search` tool works regardless.
+- **No vector/semantic search.** Membrane doesn't have embedding-based search yet. The `membrane_search` tool queries via gRPC Retrieve which uses salience-based ranking. For fulltext needs, use the bundled `scripts/membrane-search.sh` (SQL LIKE queries directly on the SQLite DB).
+- **Consolidation is early.** Membrane runs consolidation every 6h with 4 sub-consolidators, but the quality of merged records depends on your data volume and patterns.
+- **SQLite scaling.** Works well up to ~100k records. Beyond that, query performance may degrade. No sharding or distributed mode.
+
+## Membrane — Credit & Collaboration
+
+This plugin bridges [GustyCube/membrane](https://github.com/GustyCube/membrane) — a Go-based gRPC service (7.2k LOC) implementing biological memory dynamics: episodic timeline, semantic facts, competence learning, working memory, salience decay, and revision operations (supersede/fork/retract/contest/merge). The [RFC specification](https://github.com/GustyCube/membrane/blob/main/RFC.md) (849 lines) is one of the best-documented agent memory specs out there.
+
+This plugin is the **bridge layer** — it handles OpenClaw event mapping, buffered ingestion, search tooling, and context injection. Membrane does the heavy lifting on storage, decay math, and memory consolidation.
+
+- **Membrane docs:** [membrane.gustycube.com](https://membrane.gustycube.com)
+- **TS Client:** `@gustycube/membrane` on npm
+- **Memory types:** episodic (timeline), semantic (SPO triples), competence (learned patterns), working (task state)
+- **Revision ops:** supersede, fork, retract, contest, merge
+
+## Vainplex OpenClaw Plugin Suite
+
+| # | Plugin | Version | Tests | Description |
+|---|--------|---------|-------|-------------|
+| 1 | [@vainplex/openclaw-nats-eventstore](https://github.com/alberthild/openclaw-nats-eventstore) | 0.2.1 | 60 | NATS JetStream event persistence |
+| 2 | [@vainplex/openclaw-cortex](https://github.com/alberthild/openclaw-cortex) | 0.4.2 | 756 | Boot context, threads, decisions, trace analysis |
+| 3 | [@vainplex/openclaw-governance](https://github.com/alberthild/openclaw-governance) | 0.3.2 | 402 | Policy engine, trust scores, credential guard |
+| 4 | [@vainplex/openclaw-knowledge-engine](https://github.com/alberthild/openclaw-knowledge-engine) | 0.1.4 | 94 | LanceDB knowledge extraction + search |
+| 5 | **@vainplex/openclaw-membrane** | **0.3.0** | **44** | **Membrane episodic memory bridge** |
+
+## License
+
+MIT

package/assets/proto/membrane/v1/membrane.proto

@@ -0,0 +1,192 @@
+syntax = "proto3";
+
+package membrane.v1;
+
+option go_package = "github.com/GustyCube/membrane/api/grpc/gen/membranev1";
+
+service MembraneService {
+    rpc IngestEvent(IngestEventRequest) returns (IngestResponse);
+    rpc IngestToolOutput(IngestToolOutputRequest) returns (IngestResponse);
+    rpc IngestObservation(IngestObservationRequest) returns (IngestResponse);
+    rpc IngestOutcome(IngestOutcomeRequest) returns (IngestResponse);
+    rpc IngestWorkingState(IngestWorkingStateRequest) returns (IngestResponse);
+    rpc Retrieve(RetrieveRequest) returns (RetrieveResponse);
+    rpc RetrieveByID(RetrieveByIDRequest) returns (MemoryRecordResponse);
+    rpc Supersede(SupersedeRequest) returns (MemoryRecordResponse);
+    rpc Fork(ForkRequest) returns (MemoryRecordResponse);
+    rpc Retract(RetractRequest) returns (RetractResponse);
+    rpc Merge(MergeRequest) returns (MemoryRecordResponse);
+    rpc Reinforce(ReinforceRequest) returns (ReinforceResponse);
+    rpc Penalize(PenalizeRequest) returns (PenalizeResponse);
+    rpc GetMetrics(GetMetricsRequest) returns (MetricsResponse);
+    rpc Contest(ContestRequest) returns (ContestResponse);
+}
+
+// ---------------------------------------------------------------------------
+// Ingestion messages
+// ---------------------------------------------------------------------------
+
+message IngestEventRequest {
+    string source = 1;
+    string event_kind = 2;
+    string ref = 3;
+    string summary = 4;
+    string timestamp = 5;        // RFC 3339
+    repeated string tags = 6;
+    string scope = 7;
+    string sensitivity = 8;
+}
+
+message IngestToolOutputRequest {
+    string source = 1;
+    string tool_name = 2;
+    bytes args = 3;              // JSON-encoded map
+    bytes result = 4;            // JSON-encoded value
+    repeated string depends_on = 5;
+    string timestamp = 6;        // RFC 3339
+    repeated string tags = 7;
+    string scope = 8;
+    string sensitivity = 9;
+}
+
+message IngestObservationRequest {
+    string source = 1;
+    string subject = 2;
+    string predicate = 3;
+    bytes object = 4;            // JSON-encoded value
+    string timestamp = 5;        // RFC 3339
+    repeated string tags = 6;
+    string scope = 7;
+    string sensitivity = 8;
+}
+
+message IngestOutcomeRequest {
+    string source = 1;
+    string target_record_id = 2;
+    string outcome_status = 3;   // success | failure | partial
+    string timestamp = 4;        // RFC 3339
+}
+
+message IngestWorkingStateRequest {
+    string source = 1;
+    string thread_id = 2;
+    string state = 3;
+    repeated string next_actions = 4;
+    repeated string open_questions = 5;
+    string context_summary = 6;
+    bytes active_constraints = 7; // JSON-encoded []Constraint
+    string timestamp = 8;        // RFC 3339
+    repeated string tags = 9;
+    string scope = 10;
+    string sensitivity = 11;
+}
+
+message IngestResponse {
+    bytes record = 1;            // JSON-encoded MemoryRecord
+}
+
+// ---------------------------------------------------------------------------
+// Retrieval messages
+// ---------------------------------------------------------------------------
+
+message TrustContext {
+    string max_sensitivity = 1;
+    bool authenticated = 2;
+    string actor_id = 3;
+    repeated string scopes = 4;
+}
+
+message RetrieveRequest {
+    string task_descriptor = 1;
+    TrustContext trust = 2;
+    repeated string memory_types = 3;
+    double min_salience = 4;
+    int32 limit = 5;
+}
+
+message RetrieveResponse {
+    repeated bytes records = 1;  // JSON-encoded MemoryRecord array
+    bytes selection = 2;         // JSON-encoded SelectionResult, optional
+}
+
+message RetrieveByIDRequest {
+    string id = 1;
+    TrustContext trust = 2;
+}
+
+message MemoryRecordResponse {
+    bytes record = 1;            // JSON-encoded MemoryRecord
+}
+
+// ---------------------------------------------------------------------------
+// Revision messages
+// ---------------------------------------------------------------------------
+
+message SupersedeRequest {
+    string old_id = 1;
+    bytes new_record = 2;        // JSON-encoded MemoryRecord
+    string actor = 3;
+    string rationale = 4;
+}
+
+message ForkRequest {
+    string source_id = 1;
+    bytes forked_record = 2;     // JSON-encoded MemoryRecord
+    string actor = 3;
+    string rationale = 4;
+}
+
+message RetractRequest {
+    string id = 1;
+    string actor = 2;
+    string rationale = 3;
+}
+
+message RetractResponse {}
+
+message MergeRequest {
+    repeated string ids = 1;
+    bytes merged_record = 2;     // JSON-encoded MemoryRecord
+    string actor = 3;
+    string rationale = 4;
+}
+
+message ContestRequest {
+    string id = 1;
+    string contesting_ref = 2;
+    string actor = 3;
+    string rationale = 4;
+}
+
+message ContestResponse {}
+
+// ---------------------------------------------------------------------------
+// Decay messages
+// ---------------------------------------------------------------------------
+
+message ReinforceRequest {
+    string id = 1;
+    string actor = 2;
+    string rationale = 3;
+}
+
+message ReinforceResponse {}
+
+message PenalizeRequest {
+    string id = 1;
+    double amount = 2;
+    string actor = 3;
+    string rationale = 4;
+}
+
+message PenalizeResponse {}
+
+// ---------------------------------------------------------------------------
+// Metrics messages
+// ---------------------------------------------------------------------------
+
+message GetMetricsRequest {}
+
+message MetricsResponse {
+    bytes snapshot = 1;          // JSON-encoded metrics.Snapshot
+}

package/dist/buffer.js

@@ -0,0 +1,106 @@
+/**
+ * Reliability buffer for Membrane gRPC calls.
+ * Ring buffer with retry logic and exponential backoff.
+ */
+export class RingBuffer {
+    buffer;
+    head = 0;
+    tail = 0;
+    size;
+    count = 0;
+    constructor(size) {
+        this.size = size;
+        this.buffer = new Array(size).fill(null);
+    }
+    push(item) {
+        if (this.count === this.size) {
+            this.tail = (this.tail + 1) % this.size;
+            this.count--;
+        }
+        this.buffer[this.head] = item;
+        this.head = (this.head + 1) % this.size;
+        this.count++;
+        return true;
+    }
+    pop() {
+        if (this.count === 0)
+            return null;
+        const item = this.buffer[this.tail];
+        this.buffer[this.tail] = null;
+        this.tail = (this.tail + 1) % this.size;
+        this.count--;
+        return item;
+    }
+    get length() {
+        return this.count;
+    }
+}
+export class ReliabilityManager {
+    processor;
+    logger;
+    buffer;
+    processing = false;
+    retryDelay = 100;
+    maxRetryDelay = 30000;
+    maxRetries = 10;
+    constructor(size, processor, logger) {
+        this.processor = processor;
+        this.logger = logger;
+        const safeSize = Math.max(size || 0, 1000);
+        this.buffer = new RingBuffer(safeSize);
+    }
+    enqueue(method, payload) {
+        this.buffer.push({
+            method,
+            payload,
+            retries: 0,
+            timestamp: Date.now()
+        });
+        this.process();
+    }
+    async process() {
+        if (this.processing || this.buffer.length === 0)
+            return;
+        this.processing = true;
+        while (this.buffer.length > 0) {
+            const item = this.buffer.pop();
+            if (!item)
+                break;
+            try {
+                await this.processor(item);
+                this.retryDelay = 100;
+            }
+            catch (err) {
+                this.logger?.warn(`[membrane] Error processing ${item.method}: ${err instanceof Error ? err.message : String(err)}`);
+                item.retries++;
+                if (item.retries > this.maxRetries) {
+                    this.logger?.warn(`[membrane] Dropping ${item.method} after ${this.maxRetries} retries`);
+                    continue;
+                }
+                const delay = Math.min(this.retryDelay * Math.pow(2, item.retries), this.maxRetryDelay);
+                this.buffer.push(item);
+                await new Promise(resolve => setTimeout(resolve, delay));
+            }
+        }
+        this.processing = false;
+    }
+    async flush(timeoutMs) {
+        const start = Date.now();
+        let dropped = 0;
+        while (this.buffer.length > 0 && (Date.now() - start) < timeoutMs) {
+            const item = this.buffer.pop();
+            if (item) {
+                try {
+                    await this.processor(item);
+                }
+                catch (err) {
+                    dropped++;
+                    this.logger?.warn(`[membrane] Flush failed for ${item.method}, dropped (${dropped} total)`);
+                }
+            }
+        }
+        if (this.buffer.length > 0) {
+            this.logger?.warn(`[membrane] Flush timeout: ${this.buffer.length} items still in buffer`);
+        }
+    }
+}

package/dist/client.js

@@ -0,0 +1,52 @@
+/**
+ * Membrane gRPC client wrapper.
+ * Connects to the Membrane sidecar and provides typed method calls.
+ */
+import * as grpc from '@grpc/grpc-js';
+import * as protoLoader from '@grpc/proto-loader';
+import path from 'path';
+import { fileURLToPath } from 'url';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+export class MembraneClient {
+    endpoint;
+    client;
+    constructor(endpoint, customProtoPath) {
+        this.endpoint = endpoint;
+        const protoPath = customProtoPath || path.join(__dirname, 'assets/proto/membrane/v1/membrane.proto');
+        const packageDefinition = protoLoader.loadSync(protoPath, {
+            keepCase: true,
+            longs: String,
+            enums: String,
+            defaults: true,
+            oneofs: true,
+            includeDirs: [path.dirname(path.dirname(path.dirname(protoPath)))]
+        });
+        const membraneProto = grpc.loadPackageDefinition(packageDefinition);
+        this.client = new membraneProto.membrane.v1.MembraneService(this.endpoint, grpc.credentials.createInsecure());
+    }
+    async call(method, payload) {
+        return new Promise((resolve, reject) => {
+            const metadata = new grpc.Metadata();
+            const apiKey = process.env.MEMBRANE_API_KEY;
+            if (apiKey) {
+                metadata.add('authorization', apiKey);
+            }
+            if (typeof this.client[method] !== 'function') {
+                reject(new Error(`Unknown gRPC method: ${method}`));
+                return;
+            }
+            this.client[method](payload, metadata, (err, response) => {
+                if (err) {
+                    reject(err);
+                }
+                else {
+                    resolve(response);
+                }
+            });
+        });
+    }
+    close() {
+        this.client.close();
+    }
+}

package/dist/index.js

@@ -0,0 +1,181 @@
+/**
+ * @vainplex/openclaw-membrane — Membrane bridge plugin for OpenClaw
+ *
+ * Provides:
+ * - Event ingestion (write path) via gRPC IngestEvent
+ * - `membrane_search` tool for episodic memory queries
+ * - `before_agent_start` hook for auto-context injection
+ */
+import { MembraneClient } from './client.js';
+import { ReliabilityManager } from './buffer.js';
+import { mapEvent, mapSensitivity } from './mapping.js';
+import { parseMembraneRecords, selectMemories } from './parser.js';
+import { DEFAULT_CONFIG } from './types.js';
+// --- Config (exported for testing) ---
+export function createConfig(rawConfig) {
+    return {
+        ...DEFAULT_CONFIG,
+        ...validateConfig(rawConfig),
+    };
+}
+export function validateConfig(raw) {
+    const result = {};
+    if (typeof raw.grpc_endpoint === 'string')
+        result.grpc_endpoint = raw.grpc_endpoint;
+    if (typeof raw.buffer_size === 'number')
+        result.buffer_size = raw.buffer_size;
+    if (typeof raw.default_sensitivity === 'string')
+        result.default_sensitivity = raw.default_sensitivity;
+    if (typeof raw.retrieve_enabled === 'boolean')
+        result.retrieve_enabled = raw.retrieve_enabled;
+    if (typeof raw.retrieve_limit === 'number')
+        result.retrieve_limit = raw.retrieve_limit;
+    if (typeof raw.retrieve_min_salience === 'number')
+        result.retrieve_min_salience = raw.retrieve_min_salience;
+    if (typeof raw.retrieve_max_sensitivity === 'string')
+        result.retrieve_max_sensitivity = raw.retrieve_max_sensitivity;
+    if (typeof raw.retrieve_timeout_ms === 'number')
+        result.retrieve_timeout_ms = raw.retrieve_timeout_ms;
+    return result;
+}
+// --- Retrieve helper ---
+async function retrieveMemories(client, query, config, fetchLimit) {
+    const request = {
+        task_descriptor: query.substring(0, 500),
+        trust: {
+            max_sensitivity: config.retrieve_max_sensitivity,
+            authenticated: true,
+            actor_id: 'openclaw-main',
+            scopes: [],
+        },
+        memory_types: [],
+        min_salience: config.retrieve_min_salience,
+        limit: fetchLimit,
+    };
+    const result = await Promise.race([
+        client.call('Retrieve', request),
+        new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), config.retrieve_timeout_ms)),
+    ]);
+    return result;
+}
+// --- Tool handler ---
+async function handleSearch(client, config, logger, params) {
+    const query = typeof params.query === 'string' ? params.query : '';
+    const limit = Math.min(typeof params.limit === 'number' ? params.limit : 5, 20);
+    if (!query || query.length < 3) {
+        return { content: [{ type: 'text', text: 'Query too short. Please provide a more specific search.' }] };
+    }
+    try {
+        const result = await retrieveMemories(client, query, config, Math.max(limit * 10, 50));
+        if (!result?.records?.length) {
+            return { content: [{ type: 'text', text: 'No relevant memories found in Membrane.' }] };
+        }
+        const parsed = parseMembraneRecords(result.records, logger);
+        const memories = selectMemories(parsed, limit);
+        if (memories.length === 0) {
+            return { content: [{ type: 'text', text: 'No relevant memories found in Membrane.' }] };
+        }
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Found ${memories.length} memories in Membrane (${result.records.length} records scanned):\n\n${memories.join('\n\n')}`,
+                }],
+        };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { content: [{ type: 'text', text: `Membrane search failed: ${msg}` }] };
+    }
+}
+// --- Context hook handler ---
+async function handleContextInjection(client, config, logger, prompt) {
+    if (!prompt || prompt.length < 5)
+        return undefined;
+    try {
+        const fetchLimit = Math.max(config.retrieve_limit * 10, 50);
+        const result = await retrieveMemories(client, prompt, config, fetchLimit);
+        if (!result?.records?.length)
+            return undefined;
+        const parsed = parseMembraneRecords(result.records, logger);
+        const memories = selectMemories(parsed, config.retrieve_limit);
+        if (memories.length === 0)
+            return undefined;
+        const context = [
+            '<membrane-context>',
+            'Episodic memory from Membrane (conversation history, tool outputs, observations).',
+            'Treat as supplementary context — verify before stating as fact.',
+            ...memories.map((m, i) => `${i + 1}. ${m}`),
+            '</membrane-context>',
+        ].join('\n');
+        logger.info(`[membrane] Injecting ${memories.length} memories (${parsed.conversational.length} conversational + ${parsed.tool.length} tool) into context`);
+        return { prependContext: context };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        logger.debug(`[membrane] Retrieve skipped: ${msg}`);
+        return undefined;
+    }
+}
+// --- Event handler ---
+function handleEvent(event, config, reliability, logger) {
+    const normalizedEvent = {
+        type: event.type,
+        payload: (event.payload || event.data || {}),
+        context: event.context,
+    };
+    const sensitivity = mapSensitivity(normalizedEvent, config.default_sensitivity);
+    const mapped = mapEvent(normalizedEvent, sensitivity);
+    if (mapped) {
+        logger.info(`[membrane] Received event: ${event.type}`);
+        reliability.enqueue(mapped.method, mapped.payload);
+    }
+}
+// --- Shutdown handler ---
+async function handleShutdown(client, reliability, logger) {
+    logger.info('[membrane] Shutting down, flushing buffer...');
+    await reliability.flush(5000);
+    client.close();
+}
+// --- Tool schema ---
+const SEARCH_TOOL_SCHEMA = {
+    type: 'object',
+    properties: {
+        query: { type: 'string', description: 'Search query — what are you looking for? Be specific.' },
+        limit: { type: 'number', description: 'Maximum results to return (default: 5, max: 20)' },
+    },
+    required: ['query'],
+};
+// --- Plugin ---
+const plugin = {
+    id: 'openclaw-membrane',
+    name: '@vainplex/openclaw-membrane',
+    version: '0.3.0',
+    register(api) {
+        const config = createConfig(api.pluginConfig);
+        const logger = api.logger;
+        const client = new MembraneClient(config.grpc_endpoint);
+        const reliability = new ReliabilityManager(config.buffer_size, async (item) => { await client.call(item.method, item.payload); }, logger);
+        logger.info(`[membrane] Registered bridge to ${config.grpc_endpoint}`);
+        // Write path: subscribe to events
+        api.on('event', (event) => {
+            handleEvent(event, config, reliability, logger);
+        });
+        // Search tool: gRPC Retrieve (boosts salience via rehearsal)
+        api.registerTool({
+            name: 'membrane_search',
+            description: 'Search episodic memory (Membrane) for conversation history, tool outputs, and observations. Use when you need historical context about past conversations, decisions, or events. Returns the most relevant memories matching the query.',
+            parameters: SEARCH_TOOL_SCHEMA,
+            execute: (_toolCallId, params) => handleSearch(client, config, logger, params),
+        });
+        // Context hook: auto-inject Membrane memories before agent starts
+        if (config.retrieve_enabled) {
+            api.on('before_agent_start', (event) => {
+                const e = event;
+                return handleContextInjection(client, config, logger, e.prompt || e.message || '');
+            });
+        }
+        // Shutdown: flush buffer, close client
+        api.on('stop', () => handleShutdown(client, reliability, logger));
+    },
+};
+export default plugin;

package/dist/mapping.js

@@ -0,0 +1,123 @@
+/**
+ * Event mapping: OpenClaw events → Membrane gRPC payloads.
+ * Each event type has its own mapping function.
+ */
+export const VALID_SENSITIVITIES = ['public', 'low', 'medium', 'high', 'hyper'];
+// --- Sensitivity ---
+export function mapSensitivity(event, defaultConfig) {
+    const isCredentialOrAuth = event.type.includes('credential') || event.type.includes('auth');
+    let sensitivity;
+    if (isCredentialOrAuth) {
+        sensitivity = 'hyper';
+    }
+    else if (event.context?.sensitivity) {
+        sensitivity = event.context.sensitivity;
+    }
+    else if (event.context?.isPrivate || event.context?.channelType === 'dm') {
+        sensitivity = 'medium';
+    }
+    else if (event.type === 'after_tool_call') {
+        sensitivity = 'medium';
+    }
+    else {
+        sensitivity = defaultConfig || 'low';
+    }
+    if (!VALID_SENSITIVITIES.includes(sensitivity)) {
+        return 'hyper'; // Secure fallback
+    }
+    return sensitivity;
+}
+// --- Individual mappers ---
+function mapMessageReceived(payload, timestamp, sensitivity) {
+    return {
+        method: 'IngestEvent',
+        payload: {
+            source: 'openclaw',
+            event_kind: 'user_message',
+            summary: typeof payload.content === 'string' ? payload.content : '',
+            timestamp,
+            sensitivity,
+        },
+    };
+}
+function mapMessageSent(payload, timestamp, sensitivity) {
+    return {
+        method: 'IngestEvent',
+        payload: {
+            source: 'openclaw',
+            event_kind: 'assistant_message',
+            summary: typeof payload.content === 'string' ? payload.content : '',
+            timestamp,
+            sensitivity,
+        },
+    };
+}
+function mapSessionStart(timestamp, sensitivity) {
+    return {
+        method: 'IngestEvent',
+        payload: {
+            source: 'openclaw',
+            event_kind: 'session_init',
+            summary: 'New session started',
+            timestamp,
+            sensitivity,
+        },
+    };
+}
+function mapToolCall(payload, timestamp, sensitivity) {
+    return {
+        method: 'IngestToolOutput',
+        payload: {
+            source: 'openclaw',
+            tool_name: payload.toolName,
+            args: Buffer.from(JSON.stringify(payload.params || {})),
+            result: Buffer.from(JSON.stringify(payload.result || {})),
+            timestamp,
+            sensitivity,
+        },
+    };
+}
+function mapFactExtracted(payload, timestamp, sensitivity) {
+    return {
+        method: 'IngestObservation',
+        payload: {
+            source: 'openclaw',
+            subject: payload.subject,
+            predicate: payload.predicate,
+            object: Buffer.from(JSON.stringify(payload.object || {})),
+            timestamp,
+            sensitivity,
+        },
+    };
+}
+function mapTaskCompleted(payload, timestamp) {
+    return {
+        method: 'IngestOutcome',
+        payload: {
+            source: 'openclaw',
+            target_record_id: payload.targetId,
+            outcome_status: payload.success ? 'success' : 'failure',
+            timestamp,
+        },
+    };
+}
+// --- Main dispatcher ---
+export function mapEvent(event, sensitivity) {
+    const timestamp = new Date().toISOString();
+    switch (event.type) {
+        case 'message_received':
+            return mapMessageReceived(event.payload, timestamp, sensitivity);
+        case 'message_sent':
+            return mapMessageSent(event.payload, timestamp, sensitivity);
+        case 'session_start':
+            return mapSessionStart(timestamp, sensitivity);
+        case 'after_tool_call':
+            return mapToolCall(event.payload, timestamp, sensitivity);
+        case 'fact_extracted':
+            return mapFactExtracted(event.payload, timestamp, sensitivity);
+        case 'task_completed':
+            return mapTaskCompleted(event.payload, timestamp);
+        default:
+            return null;
+    }
+}

package/dist/parser.js

@@ -0,0 +1,99 @@
+/**
+ * Shared record parser — used by both membrane_search tool and before_agent_start hook.
+ * Extracts and categorizes memories from Membrane gRPC Retrieve responses.
+ *
+ * Handles all 4 memory types: episodic, semantic, competence, working.
+ * Prioritizes user/assistant messages over tool calls.
+ */
+const MIN_SUMMARY_LENGTH = 5;
+const MIN_TOOL_SUMMARY_LENGTH = 30;
+const MAX_SUMMARY_LENGTH = 500;
+/**
+ * Parse raw Membrane Retrieve records into categorized, formatted memory strings.
+ */
+export function parseMembraneRecords(rawRecords, logger) {
+    const conversational = [];
+    const tool = [];
+    for (const raw of rawRecords) {
+        try {
+            const record = JSON.parse(Buffer.from(raw).toString());
+            const tsShort = formatTimestamp(record.created_at);
+            parsePayload(record, tsShort, conversational, tool);
+        }
+        catch (err) {
+            logger?.debug(`[membrane] Failed to parse record: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    return { conversational, tool };
+}
+/**
+ * Select final memories: prioritize conversational, fill remaining with tool memories.
+ */
+export function selectMemories(parsed, limit) {
+    const result = parsed.conversational.slice(0, limit);
+    if (result.length < limit) {
+        result.push(...parsed.tool.slice(0, limit - result.length));
+    }
+    return result;
+}
+// --- Internal helpers ---
+function formatTimestamp(ts) {
+    if (!ts)
+        return '';
+    return ts.substring(0, 16).replace('T', ' ');
+}
+function parsePayload(record, tsShort, conversational, tool) {
+    const payload = record.payload;
+    switch (payload.kind) {
+        case 'episodic':
+            parseEpisodic(payload.timeline, tsShort, conversational, tool);
+            break;
+        case 'semantic':
+            parseSemantic(payload, tsShort, conversational);
+            break;
+        case 'competence':
+            parseCompetence(payload, tsShort, conversational);
+            break;
+        case 'working':
+            parseWorking(payload, tsShort, conversational);
+            break;
+    }
+}
+function parseEpisodic(timeline, tsShort, conversational, tool) {
+    if (!timeline?.length)
+        return;
+    for (const entry of timeline) {
+        const summary = entry.summary || '';
+        const kind = entry.event_kind || 'event';
+        if (summary.length < MIN_SUMMARY_LENGTH)
+            continue;
+        if (kind === 'tool_call' && summary.length < MIN_TOOL_SUMMARY_LENGTH)
+            continue;
+        const line = `[${kind} ${tsShort}] ${summary.substring(0, MAX_SUMMARY_LENGTH)}`;
+        if (kind === 'user_message' || kind === 'assistant_message' || kind === 'system_event') {
+            conversational.push(line);
+        }
+        else {
+            tool.push(line);
+        }
+    }
+}
+function parseSemantic(payload, tsShort, conversational) {
+    const { subject, predicate, object } = payload;
+    if (!subject && !predicate)
+        return;
+    const objStr = typeof object === 'string' ? object : JSON.stringify(object);
+    conversational.push(`[fact ${tsShort}] ${subject} ${predicate} ${objStr}`.substring(0, MAX_SUMMARY_LENGTH));
+}
+function parseCompetence(payload, tsShort, conversational) {
+    const desc = payload.description || payload.pattern || '';
+    if (desc) {
+        conversational.push(`[competence ${tsShort}] ${desc.substring(0, MAX_SUMMARY_LENGTH)}`);
+    }
+}
+function parseWorking(payload, tsShort, conversational) {
+    const summary = payload.context_summary || payload.state || '';
+    if (summary) {
+        conversational.push(`[working ${tsShort}] ${summary.substring(0, MAX_SUMMARY_LENGTH)}`);
+    }
+}

package/dist/types.js

@@ -0,0 +1,14 @@
+/**
+ * Type definitions for openclaw-membrane plugin.
+ * Eliminates `any` throughout the codebase.
+ */
+export const DEFAULT_CONFIG = {
+    grpc_endpoint: 'localhost:50051',
+    buffer_size: 1000,
+    default_sensitivity: 'low',
+    retrieve_enabled: true,
+    retrieve_limit: 5,
+    retrieve_min_salience: 0.1,
+    retrieve_max_sensitivity: 'medium',
+    retrieve_timeout_ms: 2000,
+};

package/openclaw.plugin.json

@@ -0,0 +1,50 @@
+{
+  "id": "openclaw-membrane",
+  "name": "@vainplex/openclaw-membrane",
+  "description": "Membrane gRPC bridge for OpenClaw — episodic memory ingestion, search tool, and auto-context injection",
+  "version": "0.3.0",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": true,
+    "properties": {
+      "enabled": {
+        "type": "boolean",
+        "default": true
+      },
+      "grpc_endpoint": {
+        "type": "string",
+        "default": "localhost:50051"
+      },
+      "buffer_size": {
+        "type": "number",
+        "default": 1000
+      },
+      "default_sensitivity": {
+        "type": "string",
+        "default": "low",
+        "enum": ["public", "low", "medium", "high", "hyper"]
+      },
+      "retrieve_enabled": {
+        "type": "boolean",
+        "default": true
+      },
+      "retrieve_limit": {
+        "type": "number",
+        "default": 5
+      },
+      "retrieve_min_salience": {
+        "type": "number",
+        "default": 0.1
+      },
+      "retrieve_max_sensitivity": {
+        "type": "string",
+        "default": "medium",
+        "enum": ["public", "low", "medium", "high", "hyper"]
+      },
+      "retrieve_timeout_ms": {
+        "type": "number",
+        "default": 2000
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@vainplex/openclaw-membrane",
+  "version": "0.3.0",
+  "type": "module",
+  "description": "Membrane gRPC bridge for OpenClaw — episodic memory ingestion, search tool, and auto-context injection via Membrane sidecar",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "dev": "vitest"
+  },
+  "dependencies": {
+    "@grpc/grpc-js": "^1.14.3",
+    "@grpc/proto-loader": "^0.7.15",
+    "nats": "^2.15.0",
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.33",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3",
+    "vitest": "^1.0.0"
+  },
+  "keywords": [
+    "openclaw",
+    "membrane",
+    "grpc",
+    "episodic-memory",
+    "plugin",
+    "agent-memory"
+  ],
+  "author": "Vainplex <dev@vainplex.de>",
+  "license": "MIT",
+  "openclaw": {
+    "id": "openclaw-membrane",
+    "extensions": [
+      "./dist/index.js"
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/alberthild/openclaw-membrane"
+  },
+  "homepage": "https://github.com/alberthild/openclaw-membrane#readme",
+  "files": [
+    "dist/",
+    "assets/",
+    "openclaw.plugin.json",
+    "README.md",
+    "CHANGELOG.md"
+  ]
+}