| name | engram-brain |
| description | Native local memory for OpenClaw agents: Capture, Cue, Project, Recall, and Consolidate conversations into a private Helix-backed brain. |
Engram Memory
You have access to Engram, a persistent local memory system for OpenClaw agents. Engram turns conversations and project artifacts into a private temporal knowledge graph, then retrieves context through the lifecycle:
Capture -> Cue -> Project -> Recall -> Consolidate
Native Helix through PyO3 is the primary OpenClaw path. It gives OpenClaw the full graph/vector/BM25 backend without Docker. Lite SQLite is a fallback; Docker full mode is only for users who explicitly choose it.
Setup
The Engram server must be running locally. No API keys are required for basic operation.
Public OpenClaw install
openclaw skills install engram-brain
Then start the native Engram runtime and connect it to OpenClaw:
curl -sSL https://raw.githubusercontent.com/Moshik21/engram/main/scripts/install.sh | bash -s -- openclaw
That one command installs Engram, adds the Helix native runtime to Engram's tool environment, starts the local server, installs this skill into OpenClaw's shared skill folder, writes OpenClaw MCP config, and runs readiness checks. Release wheels are preferred; if no compatible wheel is available, the installer builds helix-native from Engram's bundled source and reports Rust/Cargo as the only extra prerequisite. It does not silently switch to Docker.
Existing Engram install
If Engram is already installed:
engramctl quickstart --mode helix --install-openclaw --connect openclaw
If the server is already running and only OpenClaw needs wiring:
engramctl install-openclaw
engramctl connect openclaw
engramctl doctor
Manual OpenClaw MCP config
If engramctl connect openclaw cannot find the OpenClaw CLI, configure MCP manually:
openclaw mcp set engram '{"url":"http://127.0.0.1:8100/mcp","transport":"streamable-http"}'
Runtime checks
Use these commands before relying on memory:
engramctl status
engramctl doctor
openclaw skills list --eligible
openclaw mcp show engram --json
Explicit Docker fallback
curl -sSL https://raw.githubusercontent.com/Moshik21/engram/main/scripts/install.sh | bash -s -- full
Use Docker only when the user explicitly asks for full Docker mode.
Environment variables
All optional:
ANTHROPIC_API_KEY — enables richer entity extraction via Claude Haiku. Without it, Engram uses a deterministic narrow extractor (zero cost).ENGRAM_GROUP_ID — namespace for multi-brain setups. Defaults to "default". Most users never need to set this.
The REST API is available at http://127.0.0.1:8100. The OpenClaw MCP endpoint is available at http://127.0.0.1:8100/mcp. When MCP tools are visible, prefer the MCP tools; use the REST examples below as the manual fallback.
For shell-capable OpenClaw sessions where MCP tools are not visible yet, use
the compact AXI fallback before answering:
engram axi --project "$PWD" --budget 800 --timeout 3
engram axi context --project "$PWD" --budget 800 --timeout 5
engram axi recall "current task" --limit 5 --timeout 5
AXI is read-only unless the user explicitly asks you to capture with
engram axi observe --stdin or engram axi remember --stdin. OpenClaw hook
installation is not assumed; Codex and Claude Code have separate
engramctl connect <client> --axi startup hook support.
If you know the current project path, bootstrap it once at session start so
artifact-backed routing has parity with memory:
POST http://localhost:8100/api/knowledge/bootstrap
Content-Type: application/json
{"project_path": "<absolute project path>", "session_id": "<optional session id>", "include_patterns": ["docs/**/*.md", "memory/**/*.md", "exports/**/*.json"]}
Golden loop (product contract)
Full guide: docs/GOLDEN_LOOP.md. Success metric is not LongMemEval:
Fresh agent surfaces ≥1 high-signal prior Decision without a handoff doc.
Three layers:
- Passive capture — harness auto-observe /
observe (cheap, complete)
- Sparse promotion —
remember with proposals, 0–5 per compaction window
- Deliberate consolidation — offline hygiene only
Session-end promote
At session end (or before compaction), invoke skill engram-session-promote
to propose ≤5 durable facts — never session recaps. See
skills/engram-session-promote/SKILL.md. SessionEnd can write a nudge file at
~/.engram/session-promote-nudge.md.
Loop Steward (silent harness subconscious)
When memory quality or debt looks wrong (should_mop, cold Decision miss,
degraded recall), or SessionEnd steward nudge is present, the harness should
run one silent pass (≤1/session), prefer subagent:
engramctl status || engramctl start
engram loop steward-once --format json
Skill: skills/engram-loop-steward/SKILL.md. Do not narrate to the user.
Public MCP stays golden-loop only.
Open adjudication / open_work counts are graph hygiene, not product success.
MCP Core Tools (use these as the primary agent surface)
| Tool | When |
|---|
claim_authority | Session start when project-local file memory is present |
get_context | Start of each conversation — durable Decisions/Preferences first |
recall | Before answering when prior context could change the response |
observe | Only when harness cannot see high-value context (or user asks to store) |
remember | High-signal facts with proposed_entities + proposed_relationships |
intend | Prospective memory / pinned context |
Do not treat search_entities, search_facts, or eval tools as primary entry points.
When to Observe vs Remember
Harness auto-capture handles routine turns — do not re-observe every turn.
Use remember (max 5 per compaction window) when:
- Durable Decision, Preference, Person, Correction, Goal, Commitment
- You can cite a verbatim
source_span in the content
- Pass
model_tier and structured proposals (you are the extractor)
Use observe only for harness-invisible context or explicit store requests.
Reject session recaps (“what we did today”).
One fact per observe + anticipated questions
Prefer one fact per observe over multi-fact dumps — long observations never
surface for their natural single-fact questions (answer locality). When you
observe, also propose the 1–3 anticipated questions a future agent would
ask to need this memory; each becomes a question-space recall cue pointing at
the episode (max 5 per observe):
printf '%s' 'FastEmbed outage root cause: model.onnx download interrupted.' \
| engram axi observe --stdin \
--question "what was the FastEmbed outage root cause" \
--question "why are new memories missing vectors"
Phrase questions the way a future agent would ask them, not as restatements of
the content — the question wording is what gets embedded.
How to Store Memories
To observe (fast, cheap, no extraction):
POST http://localhost:8100/api/knowledge/observe
Content-Type: application/json
{"content": "<text to store>", "source": "openclaw", "questions": ["<anticipated question>"]}
questions is optional (max 5). The observe body also accepts
proposed_entities / proposed_relationships, persisted as deferred evidence
(no projection at observe time).
To remember (agent-promoted atomic facts):
POST http://localhost:8100/api/knowledge/remember
Content-Type: application/json
{
"content": "LongMemEval is not Engram north star. Continuity is the metric.",
"source": "openclaw",
"model_tier": "sonnet",
"proposed_entities": [{
"name": "LongMemEval is not Engram north star",
"entity_type": "Decision",
"source_span": "LongMemEval is not Engram north star",
"summary": "Product metric is multi-agent continuity."
}],
"proposed_relationships": [{
"subject": "Engram",
"predicate": "DECIDED",
"object": "LongMemEval is not Engram north star",
"source_span": "LongMemEval is not Engram north star"
}]
}
To forget (soft delete outdated information):
POST http://localhost:8100/api/knowledge/forget
Content-Type: application/json
{"entity_name": "<entity to forget>"}
How to Recall Memories
MCP (preferred): get_context() once per session; recall(query=..., project_path=...) when prior context matters. (Operator-only tools like route_question/search_artifacts are NOT on the public surface — never call them.)
REST fallback when MCP is unavailable:
At the start of every conversation, get broad context:
GET http://localhost:8100/api/knowledge/context
When the user references something from the past or you need relevant context:
GET http://localhost:8100/api/knowledge/recall?q=<query>&limit=5
For entity or fact lookup, use recall (with lookup_kind='entities'|'facts'
when needed). The public surface is frozen to the golden loop — do not route
around it with operator REST endpoints.
Brain windows: the local server pauses briefly (typically under a minute)
every ~2 hours while the cold brain holds the graph. A connection-refused on
127.0.0.1:8100 is transient — retry shortly rather than concluding Engram is
down.
Guidelines
- Call the context endpoint once at the start of each new conversation
- For personal continuity turns like "my son did great today" or "talked to Sarah about it", recall first.
- For install/config/current-truth questions, prefer native workspace search for exact code truth,
get_context(project_path=...) for durable decisions, and recall for prior discussion.
- For decision/history questions like "what did we decide about launching Engram publicly?", use
recall plus get_context before answering.
- When recalling, integrate information naturally. Do not say "my memory system found..."
- If recall returns no results, do not mention it. Just respond normally.
- If uncertain whether something is worth remembering, observe it
- Always prioritize the user's most recent statements over older memories if there is a conflict
- When the user corrects previously stored information, forget the old info then remember the corrected version
Memory Features
- Deep episode recall: hybrid vector + BM25 search over episodes and cues; durable facts (Decisions, Preferences, identity) surface in a reserved lane regardless of raw match strength
- Usage learning (gated): genuinely used memories can earn a bounded rank tiebreak; surfacing alone never boosts rank (echo-guarded, default off until organic usage data exists)
- Knowledge graph: Entities and relationships are extracted and connected (depth tier; the proven benefit is surfacing related episodes)
- Offline consolidation: cold-brain cycles triage, merge, calibrate, infer, adjudicate evidence and edges, replay, prune noise, compact, reflect, reindex, embed the graph, run microglia cleanup and immunity, and discover dream associations (15 phases; consumers run the bounded 2h mop, not the full pipeline)
- Memory tiers: identity-core entities are promoted to the durable semantic tier (slower decay, longer prune horizon)
- Prospective memory: Set intentions that fire when related topics come up
- Dream associations: Cross-domain creative connections discovered during consolidation
Prospective Memory (Intentions)
To set a reminder that fires when a related topic comes up:
POST http://localhost:8100/api/knowledge/intentions
Content-Type: application/json
{"trigger_text": "<topic to watch for>", "action_text": "<what to do when triggered>", "entity_names": ["<related entity>"]}
To pin a context query that refreshes after consolidation:
POST http://localhost:8100/api/knowledge/intentions
Content-Type: application/json
{"trigger_text": "<topic to keep fresh>", "action_text": "<short label>", "trigger_type": "refresh_context", "refresh_trigger": "after_consolidation"}
To list active intentions:
GET http://localhost:8100/api/knowledge/intentions
Refresh-context rows include refreshTrigger, lastRefreshed, and hasPinnedResult.
When an intention fires during recall, act on it naturally without announcing it was triggered.
Consolidation
Engram runs offline consolidation in a separate cold-brain process:
triage, merge, calibrate, infer, evidence_adjudication, edge_adjudication,
replay, prune, compact, reflect, reindex,
graph_embed, microglia, immunity, dream (15 phases). Consumer installs run a
bounded 2h "mop" (hygiene drains + adjudication + replay + prune) via the
dev.engram.brain LaunchAgent — consolidation never runs inside the hot
server process, and the REST trigger returns an error on shell-role installs.
Operators run cycles with engram brain run (never from an agent session
while the server is up).
To check consolidation status:
GET http://localhost:8100/api/consolidation/status
Proactive Notifications
Engram can push memory discoveries without being asked. Consolidation events (dream associations, entity merges) and approaching intention deadlines produce notifications automatically.
Enabled by conservative and standard profiles.
To poll pending notifications:
GET http://localhost:8100/api/knowledge/notifications?limit=20
To poll notifications since a timestamp:
GET http://localhost:8100/api/knowledge/notifications?since=1741200000.0
To dismiss notifications after acting on them:
POST http://localhost:8100/api/knowledge/notifications/dismiss
Content-Type: application/json
{"ids": ["ntf_abc123", "ntf_def456"]}
Poll notifications every 30-60 seconds. Surface high-priority notifications immediately. Dismiss after acting on them. Notifications also piggyback on MCP observe and remember responses as memory_notifications.
