Cyberpunk-grade memory for your OpenClaw agent — never forget, always recall.
Unified memory and context engine plugin for OpenClaw. Replaces OpenClaw's built-in sliding-window compaction with a DAG-based summarization system that preserves every message, adds pre-compaction fact extraction, and provides persistent cross-session memory for all your agents.
One install, one config, one database.
When a conversation grows beyond the model's context window, OpenClaw normally truncates older messages. engram instead:
- Persists every message in a local SQLite database, organized by conversation
- Summarizes chunks of older messages into summaries using your configured LLM
- Condenses summaries into higher-level nodes as they accumulate, forming a DAG (directed acyclic graph)
- Assembles context each turn by combining summaries + recent raw messages
- Provides tools (
lcm_grep,lcm_describe,lcm_expand) so agents can search and recall details from compacted history - Extracts durable facts right before compaction — decisions, preferences, entities, episodes — so they survive summarization intact
- Queries memory via
memory_queryfor semantic search across all captured knowledge
Nothing is lost. Raw messages stay in the database. Summaries link back to their source messages. Agents can drill into any summary to recover the original detail.
It feels like talking to an agent that never forgets. Because it doesn't.
Right before messages are compacted into summaries (a lossy operation), engram scans them for durable signals: architectural decisions, stated preferences, named entities, key episodes. These are extracted with fast heuristics — no LLM call, no extra latency — and stored permanently with source=pre_compaction.
This is the critical difference from a simple summarization approach: durable facts survive even after the summaries containing them have been condensed or re-summarized. Your agent remembers things you said hours ago specifically, not vaguely.
- OpenClaw with plugin context engine support
- Node.js 22+
- An LLM provider configured in OpenClaw (used for summarization)
openclaw plugins install @applied-leverage/engramIf you're running from a local OpenClaw checkout:
pnpm openclaw plugins install @applied-leverage/engramFor local plugin development, build and link your working copy:
git clone https://github.com/kelliott-cloud/engram.git
cd engram
npm install
npm run build
openclaw plugins install --link "$PWD"The install command records the plugin, enables it, and wires it into the contextEngine slot automatically.
Add these to your environment or OpenClaw config:
LCM_FRESH_TAIL_COUNT=32
LCM_INCREMENTAL_MAX_DEPTH=-1
LCM_CONTEXT_THRESHOLD=0.75FRESH_TAIL_COUNT=32— protects the last 32 messages from compaction (recent context stays raw)INCREMENTAL_MAX_DEPTH=-1— enables full cascade condensation after each compaction passCONTEXT_THRESHOLD=0.75— triggers at 75% of the model's context window, leaving headroom
For long-lived sessions (7+ days of continuous agent operation):
{
"session": {
"reset": {
"mode": "idle",
"idleMinutes": 10080
}
}
}This keeps sessions alive across idle gaps so memory accumulates over weeks, not hours.
engram is configured through plugin config or environment variables. Environment variables take precedence.
Add an engram entry under plugins.entries in your OpenClaw config:
{
"plugins": {
"entries": {
"engram": {
"enabled": true,
"config": {
"freshTailCount": 32,
"contextThreshold": 0.75,
"incrementalMaxDepth": -1
}
}
}
}
}| Variable | Default | Description |
|---|---|---|
LCM_ENABLED |
true |
Enable/disable the plugin |
LCM_DATABASE_PATH |
~/.openclaw/lcm.db |
Path to the SQLite database |
LCM_CONTEXT_THRESHOLD |
0.75 |
Fraction of context window that triggers compaction (0.0–1.0) |
LCM_FRESH_TAIL_COUNT |
32 |
Number of recent messages protected from compaction |
LCM_LEAF_MIN_FANOUT |
8 |
Minimum raw messages per leaf summary |
LCM_CONDENSED_MIN_FANOUT |
4 |
Minimum summaries per condensed node |
LCM_CONDENSED_MIN_FANOUT_HARD |
2 |
Relaxed fanout for forced compaction sweeps |
LCM_INCREMENTAL_MAX_DEPTH |
0 |
How deep incremental compaction goes (0 = leaf only, -1 = unlimited) |
LCM_LEAF_CHUNK_TOKENS |
20000 |
Max source tokens per leaf compaction chunk |
LCM_LEAF_TARGET_TOKENS |
1200 |
Target token count for leaf summaries |
LCM_CONDENSED_TARGET_TOKENS |
2000 |
Target token count for condensed summaries |
LCM_MAX_EXPAND_TOKENS |
4000 |
Token cap for sub-agent expansion queries |
LCM_LARGE_FILE_TOKEN_THRESHOLD |
25000 |
File blocks above this size are intercepted and stored separately |
LCM_LARGE_FILE_SUMMARY_PROVIDER |
"" |
Provider override for large-file summarization |
LCM_LARGE_FILE_SUMMARY_MODEL |
"" |
Model override for large-file summarization |
LCM_SUMMARY_MODEL |
(from OpenClaw) | Model for summarization (e.g. anthropic/claude-sonnet-4-20250514) |
LCM_SUMMARY_PROVIDER |
(from OpenClaw) | Provider override for summarization |
LCM_AUTOCOMPACT_DISABLED |
false |
Disable automatic compaction after turns |
LCM_PRUNE_HEARTBEAT_OK |
false |
Retroactively delete HEARTBEAT_OK turn cycles from LCM storage |
engram preserves history through compaction, but it does not change OpenClaw's core session reset policy. If sessions are resetting sooner than you want, increase OpenClaw's session.reset.idleMinutes or use a channel/type-specific override.
{
"session": {
"reset": {
"mode": "idle",
"idleMinutes": 10080
}
}
}Useful values: 1440 (1 day), 10080 (7 days), 43200 (30 days), 525600 (365 days).
Once installed, your agents automatically have access to:
| Tool | What it does |
|---|---|
lcm_grep |
Full-text search across all stored conversation history |
lcm_describe |
Get a summary with metadata for any stored summary node |
lcm_expand / lcm_expand_query |
Recursively expand summaries back to source messages |
memory_query |
Semantic search across all captured episodes and facts |
No configuration changes to your agent prompts. No new workflows to learn. The memory just works.
- Architecture
- Configuration guide
- Agent tools reference
- TUI Reference
- lcm-tui
- Optional: enable FTS5 for fast full-text search
# Run tests
npm test
# Type check
npx tsc --noEmit
# Run a specific test file
npx vitest test/engine.test.tsindex.ts # Plugin entry point and registration
src/
engine.ts # LcmContextEngine — implements ContextEngine interface
assembler.ts # Context assembly (summaries + messages → model context)
compaction.ts # CompactionEngine — leaf passes, condensation, sweeps
summarize.ts # Depth-aware prompt generation and LLM summarization
retrieval.ts # RetrievalEngine — grep, describe, expand operations
expansion.ts # DAG expansion logic for lcm_expand_query
expansion-auth.ts # Delegation grants for sub-agent expansion
expansion-policy.ts # Depth/token policy for expansion
large-files.ts # File interception, storage, and exploration summaries
integrity.ts # DAG integrity checks and repair utilities
transcript-repair.ts # Tool-use/result pairing sanitization
types.ts # Core type definitions (dependency injection contracts)
openclaw-bridge.ts # Bridge utilities
db/
config.ts # LcmConfig resolution from env vars
connection.ts # SQLite connection management
migration.ts # Schema migrations
store/
conversation-store.ts # Message persistence and retrieval
summary-store.ts # Summary DAG persistence and context item management
fts5-sanitize.ts # FTS5 query sanitization
tools/
lcm-grep-tool.ts # lcm_grep tool implementation
lcm-describe-tool.ts # lcm_describe tool implementation
lcm-expand-tool.ts # lcm_expand tool (sub-agent only)
lcm-expand-query-tool.ts # lcm_expand_query tool (main agent wrapper)
lcm-conversation-scope.ts # Conversation scoping utilities
common.ts # Shared tool utilities
test/ # Vitest test suite
specs/ # Design specifications
openclaw.plugin.json # Plugin manifest with config schema and UI hints
tui/ # Interactive terminal UI (Go)
main.go # Entry point and bubbletea app
data.go # Data loading and SQLite queries
dissolve.go # Summary dissolution
repair.go # Corrupted summary repair
rewrite.go # Summary re-summarization
transplant.go # Cross-conversation DAG copy
prompts/ # Depth-aware prompt templates
.goreleaser.yml # GoReleaser config for TUI binary releases
MIT