Engram Brain

Persistent long-term memory powered by knowledge graphs, ACT-R activation, and 15-phase consolidation. Remember conversations across sessions, recall relevan...

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.

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"]}

When to Observe vs Remember

Default to observe for most content. Use remember only for high-signal items.

Use observe when:

• General conversation context or topics discussed
• Information that might be useful later but is not critical
• Bulk context from a long conversation
• You are uncertain whether something is worth a full remember

Use remember when:

• The user explicitly asks you to remember something
• Personal identity facts (name, location, job title)
• Explicit preferences or corrections to prior knowledge
• Key decisions that will affect future interactions
• Goals, plans, or deadlines with concrete details

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"}

To remember (full extraction with entities and relationships):

POST http://localhost:8100/api/knowledge/remember
Content-Type: application/json

{"content": "<important text>", "source": "openclaw"}

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

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 project-truth questions, route first:

POST http://localhost:8100/api/knowledge/route
Content-Type: application/json

{"question": "<user question>", "project_path": "<optional project path>"}

Use the returned answerContract as response policy, not just source routing. If the route says inspect or reconcile, treat evidencePlan.requiredNextSources as mandatory. Carry the same project_path into artifact/runtime calls before answering:

GET http://localhost:8100/api/knowledge/artifacts/search?q=<query>&project_path=<optional path>&limit=5
GET http://localhost:8100/api/knowledge/runtime?project_path=<optional path>

To inspect the current brain-loop state for this user/brain:

GET http://localhost:8100/api/lifecycle/summary

Use this when deciding whether the brain has recent captures, cue coverage, projection failures, active recall context, or consolidation cycles before running heavier diagnostics.

To search for specific entities:

GET http://localhost:8100/api/entities/search?q=<name>

To search for specific facts and relationships:

GET http://localhost:8100/api/knowledge/facts?q=<query>

search_facts is user-facing by default. Internal decision/artifact graph edges stay hidden unless you explicitly opt into debug mode with include_epistemic=true.

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 like "how do we install the OpenClaw skill?" or "is full mode rework by default?", call route, then satisfy requiredNextSources before answering.
• For decision/history questions like "what did we decide about launching Engram publicly?", treat it as reconciliation: use memory plus artifacts/runtime before answering, and do not use search_facts as a substitute for artifact inspection.
• If answerContract.operator is compare, contrast raw defaults, shipped install defaults, repo posture, and runtime state when relevant.
• If answerContract.operator is reconcile or unresolved_state_report, preserve earlier discussion versus current documented or implemented truth.
• If answerContract.operator is recommend or plan, state the evidence first and then give advice or next steps.
• 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

• Activation-aware retrieval: Memories accessed more frequently and recently rank higher
• Knowledge graph: Entities and relationships are extracted and connected
• 17-phase consolidation: Offline cycles triage, merge, calibrate, infer, adjudicate evidence and edges, replay, prune noise, compact, mature entities, form schemas, reindex, embed the graph, run microglia cleanup, dissolve low-semantic-gravity noise through immunity, and discover dream associations
• Memory maturation: Entities graduate from episodic (recent) to semantic (durable) over time
• 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 17 offline consolidation phases that improve memory quality over time: triage, merge, calibrate, infer, evidence_adjudication, edge_adjudication, replay, prune, compact, mature, semanticize, schema, reindex, graph_embed, microglia, immunity, dream.

To trigger a consolidation cycle manually:

POST http://localhost:8100/api/consolidation/trigger
Content-Type: application/json

{"profile": "standard"}

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, schema patterns, maturation milestones) 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.