openclaw-engram

OpenClaw plugin that connects agents to an engram persistent memory server for long-term context retention.

Prerequisites

• OpenClaw gateway installed and running
• Engram server running and reachable (default port 37777)
• An API token configured on the engram server

Installation

Fresh install

1. Temporarily remove the memory slot if configured (avoids circular validation during install):

   # If plugins.slots.memory is currently set to "engram", clear it first:
   openclaw config set plugins.slots.memory ""

2. Install the plugin:

   openclaw plugins install openclaw-engram

   This runs npm pack and extracts the plugin into ~/.openclaw/extensions/engram/.

3. Configure the engram server connection:

   openclaw config set plugins.entries.engram.config.url http://your-engram-server:37777
   openclaw config set plugins.entries.engram.config.token your-api-token

4. Assign as the memory backend:

   openclaw config set plugins.slots.memory engram

5. Restart the gateway:

   openclaw gateway restart

Updating

openclaw plugins install openclaw-engram
openclaw gateway restart

Note on package naming

The npm package is openclaw-engram but the plugin ID is engram. OpenClaw may show a cosmetic warning about ID mismatch — this is harmless. The plugin registers and operates correctly under the engram ID.

Configuration

All fields are set under plugins.entries.engram.config:

| Field | Type | Default | Description | |---|---|---|---| | url | string | http://localhost:37777 | Engram server base URL | | token | string | (required) | Bearer token for API authentication | | project | string | (auto-detected) | Project scope override; defaults to workspace identity | | contextLimit | number | 10 | Maximum observations injected per prompt turn | | sessionContextLimit | number | 20 | Maximum observations injected at session start | | tokenBudget | number | 2000 | Token budget for context injection (~4 chars/token) | | timeoutMs | number | 5000 | Per-request HTTP timeout in milliseconds | | autoExtract | boolean | true | Auto-extract observations on compaction and session end | | workspaceDir | string | ~/.openclaw/workspace/ | Workspace path for /migrate when called from channel context (Telegram, Discord) | | logLevel | string | warn | Log verbosity: debug, info, warn, error |

What it provides

Hooks

The plugin hooks into the agent lifecycle automatically — no configuration needed:

| Hook | Effect | |---|---| | session_start | Injects up to sessionContextLimit relevant observations into system context | | before_prompt_build | Injects up to contextLimit observations relevant to the current turn | | after_tool_call | Forwards tool events to engram for self-learning | | before_compaction | Backfills conversation transcript into engram before context is compacted | | session_end | Final transcript backfill when the session closes |

Agent tools

Available to the agent during a session:

| Tool | Description | |---|---| | engram_search | Semantic search across all stored observations | | memory_search | Alias for engram_search (memory-core compatible name) | | engram_remember | Store a new observation with structured metadata | | memory_store | Alias for engram_remember | | engram_decisions | Retrieve past architectural decisions by query | | memory_get | Retrieve a specific observation by ID | | memory_forget | Delete an observation by ID | | memory_migrate | Import local MEMORY.md / memory/**/*.md files into engram |

Slash commands

| Command | Description | |---|---| | /memory | Show memory status and search | | /remember <text> | Store a memory immediately | | /migrate [--dry-run] [--force] [path] | Import local memory files into engram |

CLI

openclaw memory status              # Show server health and version
openclaw memory search <query>      # Search engram memory
openclaw memory store <text>        # Store a memory
openclaw memory migrate             # Import local memory files
openclaw memory migrate --dry-run   # Preview without importing
openclaw memory migrate --force     # Re-import already migrated files

Troubleshooting

"plugin not found: engram" during install

Circular dependency: OpenClaw tries to load the memory plugin before it is installed. Fix: clear plugins.slots.memory first (step 1 of Installation), install, then re-set the slot.

"plugin id mismatch" warning

The npm package name (openclaw-engram) differs from the plugin ID (engram). This is cosmetic — the plugin loads and works correctly. No action needed.

Plugin loads but no memory is injected into prompts

1. Verify the server is reachable: openclaw memory status
2. Check url and token are set correctly
3. Increase logLevel to debug and restart the gateway to see injection details
4. Confirm plugins.slots.memory is set to engram

Context injection is slow or times out

Increase timeoutMs (default 5000 ms). Engram failures are non-blocking — if the server is unreachable the agent continues without memory context.

Development

Requirements: Node.js >=18, TypeScript >=5.

cd plugin/openclaw-engram
npm install
npm run build       # compile TypeScript → dist/
npm run typecheck   # type-check without emitting

The compiled output in dist/ is what OpenClaw loads. Re-run npm run build after any source change and restart the gateway.