--- name: engram-brain description: Native local memory for OpenClaw agents: Capture, Cue, Project, Recall, and Consolidate conversations into a private Helix-backed brain. version: 0.3.4 homepage: https://github.com/Moshik21/engram user-invocable: true metadata: {"openclaw":{"requires":{"anyBins":["curl"]},"envVars":[{"name":"ANTHROPIC_API_KEY","required":false,"description":"Optional richer entity extraction; deterministic extraction works without it."},{"name":"ENGRAM_GROUP_ID","required":false,"description":"Optional brain namespace for multi-brain setups."}],"emoji":"\ud83e\udde0","homepage":"https://github.com/Moshik21/engram","install":[{"kind":"shell","command":"curl -sSL https://raw.githubusercontent.com/Moshik21/engram/main/scripts/install.sh | bash -s -- openclaw","bins":["engram","engramctl"]}],"tags":["memory","knowledge-graph","mcp","recall","long-term-memory","cognitive-architecture"]}} --- # 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 ```bash openclaw skills install engram-brain ``` Then start the native Engram runtime and connect it to OpenClaw: ```bash 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: ```bash engramctl quickstart --mode helix --install-openclaw --connect openclaw ``` If the server is already running and only OpenClaw needs wiring: ```bash engramctl install-openclaw engramctl connect openclaw engramctl doctor ``` ### Manual OpenClaw MCP config If `engramctl connect openclaw` cannot find the OpenClaw CLI, configure MCP manually: ```bash openclaw mcp set engram '{"url":"http://127.0.0.1:8100/mcp","transport":"streamable-http"}' ``` ### Runtime checks Use these commands before relying on memory: ```bash engramctl status engramctl doctor openclaw skills list --eligible openclaw mcp show engram --json ``` ### Explicit Docker fallback ```bash 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": "", "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": "", "source": "openclaw"} ``` To remember (full extraction with entities and relationships): ``` POST http://localhost:8100/api/knowledge/remember Content-Type: application/json {"content": "", "source": "openclaw"} ``` To forget (soft delete outdated information): ``` POST http://localhost:8100/api/knowledge/forget Content-Type: application/json {"entity_name": ""} ``` ## 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=&limit=5 ``` For project-truth questions, route first: ``` POST http://localhost:8100/api/knowledge/route Content-Type: application/json {"question": "", "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=&project_path=&limit=5 GET http://localhost:8100/api/knowledge/runtime?project_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= ``` To search for specific facts and relationships: ``` GET http://localhost:8100/api/knowledge/facts?q= ``` `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": "", "action_text": "", "entity_names": [""]} ``` To pin a context query that refreshes after consolidation: ``` POST http://localhost:8100/api/knowledge/intentions Content-Type: application/json {"trigger_text": "", "action_text": "", "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`.

Engram Brain

Description

Latest Changes

Install Engram Brain with One Click