Tools

Memory Engram

Name: Memory Engram
Rating: 3.5 (1 reviews)
Author: nikolicjakov

By nikolicjakov 👁 3 views ▲ 0 votes

OpenClaw memory plugin for Engram (github.com/Gentleman-Programming/engram) — SQLite + FTS5 persistent memory for AI agents

GitHub

Install

npm install
```

Configuration Example

{
  "plugins": {
    "allow": ["openclaw-memory-engram"],
    "load": {
      "paths": ["/path/to/openclaw-memory-engram"]
    },
    "entries": {
      "openclaw-memory-engram": {
        "enabled": true,
        "config": {
          "url": "http://127.0.0.1:7437",
          "project": "general",
          "maxResults": 10,
          "timeoutMs": 5000,
          "autoRecall": true,
          "autoCapture": false,
          "recallLimit": 5,
          "recallMinScore": 0.3
        }
      }
    }
  }
}

README

# openclaw-memory-engram

![openclaw-memory-engram](assets/banner.png)

OpenClaw plugin for [Engram](https://github.com/Gentleman-Programming/engram) — persistent
structured memory for AI agents with SQLite + FTS5 full-text search.

> **Which Engram?** This plugin integrates with
> [Gentleman-Programming/engram](https://github.com/Gentleman-Programming/engram) — the Go-based,
> agent-agnostic memory system with SQLite + FTS5, MCP server, HTTP API, CLI, and TUI.
> It is **not** related to other projects that share the "engram" name.

## The Problem

AI coding agents forget everything between sessions. Every time a conversation ends or the
context window compacts, all the decisions, discoveries, configurations, and lessons learned
vanish. The next session starts from zero — the agent doesn't know what was tried before,
what failed, what conventions were agreed on, or what the project even looks like.

This creates real problems when you work with agents daily:

- **Repeated mistakes** — the agent makes the same wrong assumption it made last week because
  it has no memory of the correction
- **Lost context** — you explained your infrastructure, credentials layout, or deployment
  process once, but after compaction the agent asks again
- **No continuity** — session summaries and handoff notes disappear, so picking up where you
  left off requires re-explaining everything
- **Wasted tokens** — you spend half your context window re-establishing what the agent
  should already know

## How This Plugin Solves It

This plugin connects OpenClaw to [Engram](https://github.com/Gentleman-Programming/engram),
giving every agent a persistent, searchable long-term memory that survives across sessions,
compactions, and restarts.

**Automatic recall** — before each agent turn, the plugin searches Engram for memories
relevant to the current message and injects them into the prompt. The agent sees past
decisions and context without you having to ask it to "check memory first".

**Structured storage** — agents save observations with types (decision, bugfix, config,
procedure, etc.), projects, and topic keys. This isn't a raw conversation dump — it's
organized knowledge that stays useful over time.

**Topic-based deduplication** — when an agent saves a memory with the same `topic_key` as
an existing one, it updates the existing memory instead of creating a duplicate. Evolving
knowledge stays consolidated in one place.

**Works alongside OpenClaw's built-in memory** — this plugin uses the `engram_*` tool
namespace, so it runs in parallel with `memory-core` (Markdown-based memory) without
conflicts. You get both systems: structured Engram observations for decisions and context,
and Markdown files for curated long-term notes.

## Features

- **11 agent tools** (`engram_*` namespace) — full memory lifecycle from search to session management
- **Automatic memory recall (RAG)** — searches Engram on every incoming message and injects relevant memories into agent context before the LLM sees the prompt
- **Smart query extraction** — strips channel metadata (Mattermost/Telegram/Discord framing, timestamps) and stop words from prompts to produce clean FTS5 search keywords
- **Progressive FTS5 fallback** — when the full keyword query returns no results, progressively drops terms until a match is found
- **Session deduplication** — memories already injected in the current session are not repeated, saving context tokens on long conversations
- **Dynamic snippet sizing** — auto-recall distributes a fixed character budget across results (more detail for fewer results, less for many)
- **Full-text search** via BM25 ranking with project/type/scope filters
- **Topic-based deduplication** — same `topic_key` updates existing memory instead of creating duplicates
- **Progressive disclosure** — search → get → timeline (token-efficient)
- **Session lifecycle** — start, context loading, save, end with summary
- **Auto-session creation** — `engram_save` auto-creates sessions (no FOREIGN KEY errors)
- **Prompt injection protection** — recalled memories are sanitized and escaped before context injection
- **Graceful degradation** — all tools return clean error messages if Engram is unreachable
- **Coexists with memory-core** — no tool name conflicts, both systems work in parallel
- **CLI tools** — `openclaw engram search/get/recent/context/status/migrate/suggest-key/export/import`
- **Compaction awareness** — logs compaction events for diagnostics

## How Auto-Recall Works

When `autoRecall` is enabled (default), the plugin hooks into `before_prompt_build` and
`before_agent_start` to intercept every incoming message before the agent processes it:

```
User message → Strip channel metadata → Extract keywords → Search Engram
                                                              ↓
                                              Score & filter results
                                                              ↓
                                              Deduplicate (skip already-seen)
                                                              ↓
                                              Budget snippet size per result
                                                              ↓
                                              Inject as prependContext with IDs
                                                              ↓
                                              Agent sees memories + prompt
```

1. **Channel metadata stripping** — removes system framing like `System: [2026-03-28 16:39 UTC] Mattermost DM from @user:` that would pollute FTS5 search
2. **Stop word removal** — filters out common words ("what", "how", "please", "my", etc.) that have no value in a full-text search
3. **Progressive fallback** — FTS5 uses AND logic by default, so `kubernetes cluster configuration` fails if "configuration" isn't indexed. The plugin progressively drops trailing keywords (`kubernetes cluster` → `kubernetes`) until results appear
4. **Relevance filtering** — results are BM25-scored and filtered by `recallMinScore` threshold
5. **Session deduplication** — memories already injected earlier in the same session are skipped, avoiding repeated context on long conversations
6. **Dynamic snippet sizing** — a total character budget (1500 chars) is divided across results: 1 result gets the full budget, 5 results get 300 chars each
7. **Observation IDs included** — each injected snippet includes `[#ID]` so agents can call `engram_get` for full content
8. **Injection protection** — each memory is checked against prompt injection patterns and HTML-escaped before being added to context

## Prerequisites

### 1. Install and run Engram

Engram is a standalone Go binary. See [Engram installation docs](https://github.com/Gentleman-Programming/engram/blob/main/docs/INSTALLATION.md) for all options.

```bash
# macOS / Linux (Homebrew)
brew install gentleman-programming/tap/engram

# From source
git clone https://github.com/Gentleman-Programming/engram.git
cd engram && go install ./cmd/engram

# Or download a binary from GitHub Releases:
# https://github.com/Gentleman-Programming/engram/releases
```

Start the HTTP server (default port 7437):

```bash
engram serve
```

Verify it's running:

```bash
curl http://127.0.0.1:7437/health
```

For production, run as a systemd service:

```ini
[Unit]
Description=Engram Memory Server
After=network.target

[Service]
ExecStart=/usr/local/bin/engram serve
Restart=always
Environment=ENGRAM_DATA_DIR=/path/to/.engram

[Install]
WantedBy=default.target
```

### 2. OpenClaw

- OpenClaw >= 2026.3.13
- Node.js >= 22

## Installation

Clone the plugin to a local directory:

```bash
git clone https://github.com/nikolicjakov/openclaw-memory-engram.git
cd openclaw-memory-engram && npm install
```

## Configuration

Add to your `openclaw.json`. The `paths` array must point to the absolute path where you
cloned the plugin — this is how OpenClaw discovers and loads it:

```jsonc
{
  "plugins": {
    "allow": ["openclaw-memory-engram"],
    "load": {
      "paths": ["/path/to/openclaw-memory-engram"]
    },
    "entries": {
      "openclaw-memory-engram": {
        "enabled": true,
        "config": {
          "url": "http://127.0.0.1:7437",
          "project": "general",
          "maxResults": 10,
          "timeoutMs": 5000,
          "autoRecall": true,
          "autoCapture": false,
          "recallLimit": 5,
          "recallMinScore": 0.3
        }
      }
    }
  }
}
```

Then restart the gateway:

```bash
openclaw gateway restart
```

### Tool visibility

If your agents use `tools.profile: "coding"` or `tools.profile: "messaging"`, plugin tools may not
be visible. Set `tools.profile: "full"` globally or add `"openclaw-memory-engram"` to `tools.allow`:

```jsonc
{
  "tools": {
    "profile": "full"
  }
}
```

### Replacing memory-core entirely

If you want agents to use Engram as their **only** memory system and stop using the built-in
Markdown-based `memory-core` tools, you can deny them globally in your `openclaw.json`:

```jsonc
{
  "tools": {
    "profile": "full",
    "deny": ["memory_search", "memory_get"]
  }
}
```

This blocks the core `memory_search` and `memory_get` tools for all agents while keeping
the `engram_*` tools available. Agents will no longer attempt to search Markdown files for
memory and will rely exclusively on Engram.

This is optional. By default the plugin coexists with `memory-core` and both systems work
in parallel.

## Coexistence with memory-core

This plugin runs **alongside** `memory-core`, not as a replacement. Do NOT set
`plugins.slots.memory` to `memory-engram` unless you want to disable Markdown memory entirely.

| System | Searches | Tool names | Purpose |
|--------|----------|------------|---------|
| `memory-core` | Markdown files (`MEMORY.md`, `memory/*.md`) | `memory_search`, `memory_get` | Daily logs, curated long-term notes |
| `memory-engram` | Engram database (SQLite + FTS5) | `engram_*` (11

... (truncated)

tools