Engram Documentation

Causal memory for AI agents. Not just what happened — why.

Quickstart

BYOK (open-source, free)

# Install
pip install engram-causal

# Set your Anthropic key (only needed for free-text extraction)
export ANTHROPIC_API_KEY=sk-ant-...

# Install hooks for Claude Code
engram install

# Extract a causal triple from free text
engram extract "WeatherAPI timed out because the server was overloaded"

# Query root cause
engram why "WeatherAPI"

How it works

Three-track pipeline. LLM only called once per unique text. Everything else is local.

Confidence tagging — every triple is tagged:

• EXTRACTED — found directly in structured event fields (confidence 1.0)
• INFERRED — extracted by Claude from free-text (confidence 0.0–1.0)
• AMBIGUOUS — below threshold, kept for exploration

CLI reference

# Extract causal triples from free text
engram extract "WeatherAPI timed out because server was overloaded"

# Ingest structured event log (zero LLM)
engram ingest ./logs/session.json

# Query root cause (backward DFS, zero LLM)
engram why "WeatherAPI"

# Point-in-time causal query
engram why "PaymentService" --before 2024-03-01

# Start local API server
engram serve

# Start MCP stdio server
engram serve --mcp

# Install hooks for your platform
engram install                        # Claude Code (PreToolUse + PostToolUse)
engram install --platform cursor      # Cursor rules
engram install --platform codex       # Codex AGENTS.md + hook

SDK reference

Basic client

import engram

# BYOK — bring your own Anthropic key
client = engram.Client(anthropic_api_key="sk-ant-...")

# Extract and store
triples = await client.extract("WeatherAPI timed out because server overloaded")
await client.store(triples)

# Why-query
result = await client.why("WeatherAPI")
print(result.explanation)
print(result.top_causes)

Agent decorator

import engram

@engram.wrap(entity="PaymentService")
async def my_agent(task: str) -> str:
    # Engram auto-injects causal context before execution
    # Auto-ingests outcome as structured event after
    ...

Hook setup

Hooks are the core of the agent performance loop. PreToolUse injects causal context before every tool call. PostToolUse ingests the outcome back into the graph.

Claude Code

engram install
# Writes .claude/settings.json hooks + CLAUDE.md section
# PreToolUse: fires before Bash/Glob/Read → injects top causal chain (≤500 tokens)
# PostToolUse: fires after tool completes → ingests outcome as structured event

Cursor

engram install --platform cursor
# Writes .cursor/rules/engram.mdc with alwaysApply: true

Codex

engram install --platform codex
# Writes AGENTS.md + .codex/hooks.json PreToolUse hook

MCP server

# Start MCP stdio server
engram serve --mcp

# .mcp.json
{
  "mcpServers": {
    "engram": {
      "type": "stdio",
      "command": "engram",
      "args": ["serve", "--mcp"]
    }
  }
}

MCP tools exposed:

• why_query(entity, max_depth, min_confidence) — backward DFS causal chain
• store_triple(cause, effect, mechanism, confidence) — persist a causal triple
• ingest_events(events) — batch ingest structured event log

API reference

Token costs

Changelog

Canonical release history: CHANGELOG.md · GitHub release bodies: RELEASE_NOTES.md