OpenClaw plugin adds persistent memory with Engram server

A developer created a TypeScript plugin that connects OpenClaw agents to Engram, a lightweight Go-based memory server that stores structured observations in SQLite with FTS5 full-text search. This provides long-term memory for agents that survives restarts, compactions, and session ends.

How it works

The plugin intercepts incoming messages before each agent turn, extracts keywords, searches Engram, and injects relevant memories into the prompt automatically. This happens through a progressive fallback search: FTS5 uses AND logic, so the system drops keywords one by one until something matches. Results are scored by BM25 relevance, and the plugin skips anything already injected in the session to avoid repeated context.

What agents save

Memories aren't chat dumps but typed observations with categories like decision, bugfix, config, procedure, discovery, and pattern. These are tagged with projects and topic keys. When an agent saves something with the same topic_key as an existing memory, it updates instead of duplicating, allowing knowledge to evolve in place.

Examples of what gets stored include infrastructure preferences and constraints, service credentials and CLI wrappers for each environment, port reservations and deployment conventions, and step-by-step procedures for recurring tasks.

Technical details

The plugin is approximately 750 lines of TypeScript and gives agents 11 tools, 4 lifecycle hooks, and a CLI. It uses the engram_* namespace to coexist with OpenClaw's built-in Markdown memory without conflicts.

Key implementation details:

• Strips channel metadata (Mattermost/Telegram framing, timestamps) before searching to avoid polluted results
• Removes stop words and extracts meaningful keywords
• Dynamically sizes snippets: 1 result gets more detail, 5 results get shorter summaries
• Injects everything with observation IDs so agents can call engram_get for full content

Setup requirements

• Install Engram: brew install gentleman-programming/tap/engram or grab the binary
• Run engram serve (default port 7437, SQLite database, zero config)
• Clone the plugin and use npm for installation
• Set tools.profile: "full" in your config to make plugin tools visible to agents

Problems encountered and solutions

• FTS5 AND logic: Searching "kubernetes cluster configuration" returns nothing if any single term isn't indexed. Fixed with progressive keyword fallback.
• Channel metadata in prompts: Messages from Mattermost arrive with framing that pollutes searches. Solution is to strip metadata first.
• Plugin tools invisible to agents: OpenClaw's tools.profile: "coding" filters out plugin-registered tools. Fix is tools.profile: "full".