Cogmem Openclaw

Name: Cogmem Openclaw
Rating: 3.5 (1 reviews)
Author: cogmemory

By cogmemory 👁 50 views ▲ 0 votes

CogMemory plugin for OpenClaw — lifecycle-hook plugin with HA, auto-failover, persistent retain queue

GitHub

Install

npm install
npm

Configuration Example

{
  "plugins": {
    "allow": ["memory-cogmem-v2"],
    "load": {
      "paths": ["~/.openclaw/extensions/memory-cogmem-v2"]
    },
    "slots": {
      "memory": "memory-cogmem-v2"
    },
    "entries": {
      "memory-core": { "enabled": false },
      "memory-cogmem-v2": {
        "enabled": true,
        "config": {
          "cogmemUrl": "http://YOUR_COGMEM_SERVER:8888"
        }
      }
    },
    "installs": {
      "memory-cogmem-v2": {
        "source": "path",
        "sourcePath": "~/.openclaw/extensions/memory-cogmem-v2",
        "installPath": "~/.openclaw/extensions/memory-cogmem-v2",
        "version": "0.1.0"
      }
    }
  }
}

README

# CogMem OpenClaw Plugin

Long-term memory for [OpenClaw](https://github.com/anomalyco/openclaw) agents powered by [CogMemory](https://github.com/cogmemory). Automatically captures conversations and recalls relevant memories before each agent turn.

## Install

### Option A: One-line install

```bash
git clone https://github.com/cogmemory/cogmem-openclaw-plugin.git
cd cogmem-openclaw-plugin && bash install.sh
```

This builds the TypeScript, copies output to `~/.openclaw/extensions/memory-cogmem-v2/`, and prints the configuration snippet.

### Option B: Manual build + deploy

```bash
git clone https://github.com/cogmemory/cogmem-openclaw-plugin.git
cd cogmem-openclaw-plugin
npm install
npm run build

# Copy to OpenClaw extensions directory
mkdir -p ~/.openclaw/extensions/memory-cogmem-v2
cp -r dist/* ~/.openclaw/extensions/memory-cogmem-v2/
cp package.json ~/.openclaw/extensions/memory-cogmem-v2/
```

## Configure

Edit `~/.openclaw/openclaw.json` and merge the following into the `plugins` section:

```json
{
  "plugins": {
    "allow": ["memory-cogmem-v2"],
    "load": {
      "paths": ["~/.openclaw/extensions/memory-cogmem-v2"]
    },
    "slots": {
      "memory": "memory-cogmem-v2"
    },
    "entries": {
      "memory-core": { "enabled": false },
      "memory-cogmem-v2": {
        "enabled": true,
        "config": {
          "cogmemUrl": "http://YOUR_COGMEM_SERVER:8888"
        }
      }
    },
    "installs": {
      "memory-cogmem-v2": {
        "source": "path",
        "sourcePath": "~/.openclaw/extensions/memory-cogmem-v2",
        "installPath": "~/.openclaw/extensions/memory-cogmem-v2",
        "version": "0.1.0"
      }
    }
  }
}
```

Replace `YOUR_COGMEM_SERVER` with the actual CogMemory server address.

**Important**: Set `"memory-core": { "enabled": false }` to disable OpenClaw's built-in memory so it doesn't conflict.

## Verify

```bash
# 1. Check server is reachable
curl http://YOUR_COGMEM_SERVER:8888/health
# Expected: {"status":"healthy"}

# 2. Restart gateway and check plugin loaded
openclaw gateway
# Look for: [plugins] [CogMem] Plugin loaded, hooks registered

# 3. List plugins
openclaw plugins list | grep cogmem
# Expected: memory-cogmem-v2 | loaded
```

## How It Works

```
User sends message
        |
        v
 before_prompt_build hook
   |-> recall relevant memories from CogMemory
   |-> inject as <cogmem_memories> block in system prompt
        |
        v
 Agent generates response (with memory context)
        |
        v
 agent_end hook
   |-> capture conversation transcript
   |-> POST to CogMemory retain (async)
   |-> CogMemory extracts facts, entities, links in background
```

**Auto-recall**: Before each agent turn, the plugin searches CogMemory for memories relevant to the user's message and injects them into the system prompt. The agent sees the memories as context but users don't see the injection.

**Auto-retain**: After each agent turn, the plugin captures the conversation transcript and sends it to CogMemory. The server extracts structured facts, resolves entities, and creates semantic/temporal links in the background.

## Configuration Reference

### Required

| Option | Description |
|--------|-------------|
| `cogmemUrl` | CogMemory server URL or array of URLs for HA, e.g. `"http://YOUR_SERVER:8888"` or `["http://host1:8888", "http://host2:8888"]` |

### Bank ID

Each user's memories are stored in a single **bank**. All channels (Telegram, Slack, Discord, etc.) share the same bank so memories are available everywhere.

| Option | Default | Description |
|--------|---------|-------------|
| `bankId` | auto-generated | Fixed bank ID for this user |
| `bankIdPrefix` | — | Optional prefix (e.g. `prod` -> `prod-<bankId>`) |
| `bankMission` | — | Agent identity description, stored as retain_mission |

**How bank ID is resolved** (checked in order):

1. **`bankId` in config** — use this value directly. Recommended for production: set it to the user's unique identifier (e.g. `"zhehaozhang"`).
2. **Persisted state file** — `~/.openclaw/data/cogmem-bank-id.json`. If a previous session already generated an ID, it's reused.
3. **Auto-generate** — on first start, creates `user-<sha256(username@hostname)[:12]>` and saves it to the state file.

This means: configure `bankId` once, or leave it empty and the plugin generates a stable ID automatically. Either way, the same bank is used across all sessions and channels.

### Recall

| Option | Default | Description |
|--------|---------|-------------|
| `autoRecall` | `true` | Inject memories before each turn |
| `recallBudget` | `"mid"` | Retrieval effort: `low`/`mid`/`high` |
| `recallMaxTokens` | `1024` | Max token budget for recall response |
| `recallTypes` | `["world","experience"]` | Fact types to retrieve |
| `recallTopK` | unlimited | Max memories to inject |
| `recallContextTurns` | `1` | Prior turns included in recall query |
| `recallMaxQueryChars` | `800` | Max chars for recall query |
| `recallTimeoutMs` | `5000` | Recall timeout in ms |
| `recallInjectionPosition` | `"user"` | Where to inject (see below) |
| `recallPromptPreamble` | (built-in) | Instruction text above memories |

**`recallInjectionPosition` options:**

| Value | Position | Prompt cache | Best for |
|-------|----------|-------------|----------|
| `"user"` (default) | Before user message, in message context | Not affected | Most use cases — keeps system prompt clean, memories close to the question |
| `"append"` | End of system prompt | Preserved (static prefix cached) | When you want memories in system context but still cacheable |
| `"prepend"` | Start of system prompt | Broken (dynamic prefix) | Maximum LLM attention on memories, at the cost of cache |

### Retain

| Option | Default | Description |
|--------|---------|-------------|
| `autoRetain` | `true` | Capture conversations after each turn |
| `retainRoles` | `["user","assistant"]` | Roles to include in transcript |
| `retainEveryNTurns` | `1` | Retain frequency (>1 = chunked) |
| `retainOverlapTurns` | `0` | Extra turns in sliding window (only effective when `retainEveryNTurns` > 1) |

### High Availability

| Option | Default | Description |
|--------|---------|-------------|
| `healthCheckIntervalMs` | `30000` | Background heartbeat interval for unhealthy endpoints (0 = disabled) |
| `recallCacheTtlMs` | `1800000` | TTL for recall cache used when all endpoints down (0 = disabled) |

See [High Availability](#high-availability) section below for details.

### Other

| Option | Default | Description |
|--------|---------|-------------|
| `excludeProviders` | `[]` | Skip recall/retain for these providers |
| `logLevel` | `"info"` | `off`/`error`/`warning`/`info`/`debug` |
| `debug` | `false` | Enable verbose logging |

## Example Configurations

### Minimal (auto-generated bank ID)

```json
{
  "cogmemUrl": "http://YOUR_SERVER:8888"
}
```

Bank ID is auto-generated on first start and persisted for reuse.

### Explicit bank ID (recommended for production)

```json
{
  "cogmemUrl": "http://YOUR_SERVER:8888",
  "bankId": "zhehaozhang",
  "bankMission": "Personal AI assistant with long-term memory"
}
```

### Multi-bot isolation (same user, different bots)

```json
{
  "cogmemUrl": "http://YOUR_SERVER:8888",
  "bankId": "zhehaozhang-coding",
  "bankMission": "Programming assistant"
}
```

Use a different `bankId` per bot so each bot has its own memory space.

### High-recall, low-retain frequency

```json
{
  "cogmemUrl": "http://YOUR_SERVER:8888",
  "recallBudget": "high",
  "recallMaxTokens": 2048,
  "recallTopK": 10,
  "retainEveryNTurns": 5,
  "retainOverlapTurns": 2
}
```

### Multi-endpoint high availability

```json
{
  "cogmemUrl": [
    "http://YOUR_SERVER:8888",
    "http://YOUR_SERVER_2:8888",
    "http://YOUR_SERVER_3:8888"
  ],
  "bankId": "zhehaozhang",
  "healthCheckIntervalMs": 30000,
  "recallCacheTtlMs": 1800000
}
```

### Debug mode

```json
{
  "cogmemUrl": "http://YOUR_SERVER:8888",
  "debug": true,
  "logLevel": "debug"
}
```

## High Availability

The plugin provides client-side HA — no load balancer or service mesh required. CogMemory is stateless (all data in PostgreSQL), so multiple instances pointing to the same database are interchangeable.

### How it works

```
Plugin request (recall/retain)
       │
       ▼
  pickEndpoint() ── round-robin across healthy endpoints
       │
       ├── success → markHealthy() + return result
       │
       └── failure (5xx / timeout / network error)
              │
              ├── markUnhealthy() → try next endpoint
              │
              └── all endpoints exhausted
                     │
                     ├── recall → return cached results (if within TTL)
                     └── retain → push to JSONL retry queue
```

**Background heartbeat** (every 30s by default): probes `GET /health` on unhealthy endpoints. When an endpoint recovers, it's returned to the healthy pool and the retain queue is flushed.

### Degradation levels

| State | Recall | Retain | User impact |
|-------|--------|--------|-------------|
| All healthy | Round-robin requests | Round-robin requests | None |
| Some endpoints down | Auto-failover to healthy ones | Auto-failover | None (slightly higher latency) |
| All endpoints down | Return cached results (30min TTL) | Buffer to JSONL queue | Agent works without memory context; conversations saved locally |
| Endpoints recover | Heartbeat detects, resumes normal | Heartbeat detects, flushes queue | Automatic recovery |

### Single vs multi-endpoint

Single URL works exactly as before — all HA features are transparent:

```json
{ "cogmemUrl": "http://YOUR_SERVER:8888" }
```

The recall cache and retain queue still provide graceful degradation if this single endpoint goes down.

### Prerequisites for multi-endpoint

All CogMemory instances must share the same PostgreSQL database. The `deploy.sh` script deploys one instance; to add more, start additional instances on different hosts pointing to the sa

... (truncated)

tools