engram-brain（印迹脑）

Engram Memory

You have access to Engram, a persistent memory system that builds a temporal knowledge graph from conversations. It uses ACT-R cognitive architecture for activation-aware retrieval and runs offline consolidation inspired by biological memory.

Works with both lite (SQLite) and full (HelixDB Docker) Engram installs. Zero LLM cost by default — all consolidation scoring, replay, and retrieval are deterministic. Optional Anthropic API key enables richer entity extraction.

Setup

The Engram server must be running locally. No API keys are required for basic operation.

Package install (recommended)

uv tool install engram
engramctl setup
engramctl start
engramctl install-openclaw

Docker install

docker pull ghcr.io/moshik21/engram:latest
docker run -d -p 8100:8100 --name engram ghcr.io/moshik21/engram:latest

Then add the OpenClaw skill:

engramctl install-openclaw

Source install

Clone the repo, review the code, then build locally:

git clone https://github.com/Moshik21/engram.git ~/engram
cd ~/engram/server
uv sync
uv run engram setup
uv run engram serve

Installer script (alternative)

An interactive installer is available. Review it before running:

# Review first:
curl -sSL https://raw.githubusercontent.com/Moshik21/engram/main/scripts/install.sh -o install.sh
less install.sh
# Then run:
bash install.sh

MCP Server

For Claude Desktop / Claude Code integration:

uv run engram mcp                                          # stdio (default)
uv run engram mcp --transport streamable-http --port 8200  # HTTP

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. Check status with engramctl status.

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

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 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
• 15-phase consolidation: Offline cycles merge duplicates, infer missing links, adjudicate evidence, prune noise, mature entities, form schemas, and discover cross-domain patterns
• 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

{"query": "<topic to watch for>", "action": "<what to do when triggered>", "entity_names": ["<related entity>"]}

To list active intentions:

GET http://localhost:8100/api/knowledge/intentions

When an intention fires during recall, act on it naturally without announcing it was triggered.

Consolidation

Engram runs 15 offline consolidation phases that improve memory quality over time: triage, merge, infer, evidence_adjudicate, edge_adjudicate, replay, prune, compact, mature, semanticize, schema, reindex, graph_embed, microglia, 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