engram-causal 0.1.4

Causal memory for AI agents — not just what happened, why.

🔍 Engram

Causal memory for AI agents. Type /engram in Claude Code, Cursor, or Codex — it captures why things happen in your agent sessions, stores causal chains in a graph, and surfaces root causes before your agent repeats the same mistake.

Not just what happened. Why.

WITHOUT Engram — debugging a payment failure:
  read payment_service.py       800 tokens
  read auth_middleware.py       600 tokens
  read logs/2024-03-01.log    1,200 tokens
  Claude analyzes all above   3,500 tokens
  Total: ~6,100 tokens, 5 turns

WITH Engram (warm graph):
  hook injects causal chain     200 tokens
  → "auth_middleware.py:47 — token expiry check uses < not <= (conf: 0.94)"
  edit auth_middleware.py:47
  Total: ~200 tokens, 2 turns  →  ~30x reduction

How it works

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

input → structured JSON event?
  YES → rule_extractor()  → CausalTriple (confidence=EXTRACTED, $0.00)
  NO  → SHA256 cache hit?
    YES → cached triples  ($0.00)
    NO  → claude_extractor() → CausalTriple (confidence=INFERRED) + cache

Track A — rule-based (zero LLM): OpenTelemetry spans, typed JSON agent logs → deterministic extraction. cause, effect, mechanism read directly from event fields. confidence=EXTRACTED.

Track B — SHA256 cache (zero LLM): Same free-text log seen before → serve cached triples instantly. No API call.

Track C — LLM fallback: Claude Haiku extracts causal triples from novel free-text once → cached forever. ~$0.0003/1K tokens.

Why-queries: Backward DFS over the causal graph — no LLM, pure graph math. Returns ranked chains + confidence scores + EU AI Act Article 13 audit trail.

Hook loop (bidirectional):

• PreToolUse — injects top causal chain (≤500 tokens) before every agent tool call
• PostToolUse — ingests tool outcome as structured event → graph reinforces or supersedes existing triple
• Every session makes the next one cheaper. Agents stop re-investigating failures they've already seen.

Every relationship tagged: EXTRACTED (found directly), INFERRED (Claude extraction, with confidence score), AMBIGUOUS (below threshold, kept for exploration).

Install

Requires: Python 3.10+

# Recommended
uv tool install engram-causal && engram install

# or pip
pip install engram-causal && engram install

BYOK (open-source, free):

export ANTHROPIC_API_KEY=sk-ant-...   # only needed for free-text extraction
                                       # structured events + why-queries: zero LLM
engram install                         # Claude Code: PreToolUse + PostToolUse hooks

Hosted (no Anthropic key needed):

pip install engram-causal
engram login   # enter your engram_api_key from engram.viberank.co.in/dashboard

Platform support

Platform	Install command
Claude Code	engram install
Cursor	engram install --platform cursor
Codex	engram install --platform codex
Any (MCP)	engram serve --mcp

Claude Code installs a PreToolUse hook (fires before every Bash/Glob/Read) + a PostToolUse hook (fires after). PreToolUse injects the top causal chain for the current entity. PostToolUse ingests the outcome back into the graph.

Cursor writes .cursor/rules/engram.mdc with alwaysApply: true.

Codex writes AGENTS.md + .codex/hooks.json PreToolUse hook.

Token budget: hook injects max 500 tokens (configurable via ENGRAM_HOOK_BUDGET).

Usage

# Extract causal triples from free text
engram extract "WeatherAPI timed out because the 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

# Open the local causal graph viewer in your browser
engram graph

# Start MCP stdio server (for agent tool use)
engram serve --mcp

# Install hooks for your platform
engram install                        # Claude Code
engram install --platform cursor      # Cursor
engram install --platform codex       # Codex

# Log in to hosted API
engram login

Output

engram-out/
├── ENGRAM_REPORT.md   top entities, root causes, confidence distribution, LLM calls vs cache hits
├── graph.json         persistent causal graph — survives across sessions
└── cache/             SHA256 cache — re-runs skip already-extracted text

LLM cost profile

Event type	LLM cost	Reason
Structured JSON event	$0.00	Rule-based extractor
Repeated free-text log	$0.00	SHA256 cache hit
New free-text (first time)	~$0.0003/1K tokens	Claude Haiku → cached
Why-query (DFS traversal)	$0.00	Graph math, no LLM
Explanation synthesis	$0.00	Template engine

Typical 100-event agent session: ~$0.002 total. Subsequent runs: $0.00.

Worked examples

Scenario	Events	LLM calls	Result
Structured OpenTelemetry logs	200 events	0	Zero LLM, zero cost
Mixed logs (structured + free-text)	100 events	~20 (new text only)	~80% LLM reduction
Repeated agent session (warm cache)	100 events	0	~30x token reduction vs re-investigation

Differentiation vs vector memory

	Vector memory (Mem0, Zep)	Engram causal memory
Retrieves	Semantically similar content	Causally upstream content
Answers	"What's related to X?"	"Why did X happen?"
Method	Embeddings + ANN search	Graph DFS (no embeddings)
Cost	Embedding API per query	$0 per why-query
Explainability	Low (distance score)	High (confidence + mechanism + audit trail)

Privacy

• Structured events: processed locally, zero network
• Repeated text: served from local SHA256 cache, zero network
• New free-text: sent to Anthropic (BYOK) or Engram's API (hosted)
• Why-queries: zero network (local graph traversal)
• No telemetry, no usage tracking

Hosted API + pricing

engram.viberank.co.in/pricing

• Free — $0, self-hosted, BYOK
• Pro (Coming Soon) — $19/mo, hosted API + LLM included, 50K tokens/mo, cloud graph
• Team (Coming Soon)— $49.5 seats, shared org graph, multi-agent tracking, audit log export
• Enterprise (Coming Soon) — custom, on-premise, custom LLM backend, SSO

Powered by Dodopayments. Cancel anytime.

Changelog

Canonical release history: CHANGELOG.md

Copy-ready GitHub release bodies: RELEASE_NOTES.md

v0.1.4

• 40eefcc - normalization entity added with fallback

v0.1.3

• 195e91d - version updated
• 2bc1afc - fix: codex network access to engram with rule

v0.1.2

• ac54283 - fix: published version updated with CI

v0.1.1

• b5586f7 - Add PyPI project description metadata

v0.1.0

• af3ca1b - Use PyPI API token for publishing
• 6bf0122 - causal graph in CLI mode activated
• 4dbba73 - fix: cache import changed with hosted fastapi app for hosted users
• a2fbf5f - per org kuzu graph in s3
• f86f7a7 - engram install hooks for claude code

Release process checklist

1. Update [project].version in pyproject.toml (for example 0.1.5).
2. Generate release notes/changelog section from git history:

python scripts/generate_release_notes.py --version 0.1.5 --apply

3. Review the generated entries in CHANGELOG.md and RELEASE_NOTES.md.
4. Commit and push to main.
5. Create and push a new tag that matches the version exactly: vX.Y.Z.
6. Verify GitHub Actions Publish to PyPI succeeds for the tag.
7. Verify package visibility on PyPI: https://pypi.org/project/engram-causal/.
8. Publish/update the GitHub Release body using the corresponding section in RELEASE_NOTES.md.

Notes:

• Do not force-push release tags.
• Never reuse an already-published version number on PyPI.
• Tag and pyproject.toml version must match.

Tech stack

FastAPI + Kuzu (graph DB) + Claude Haiku (extraction, BYOK or hosted) + NetworkX + Pydantic v2.

No Neo4j required. No server required for local use. Runs entirely locally on the free tier.

MCP server

engram serve --mcp

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

MCP tools: why_query, store_triple, ingest_events.

Contributing

Worked examples are the most trust-building contribution. Run engram ingest on a real agent session, save output to worked/{slug}/, write a short review.md, submit a PR.

Extraction bugs — open an issue with the input text/event, the cached result from engram-out/cache/, and what was missed or wrong.

See ARCHITECTURE.md for module responsibilities and how to add a new event schema to the rule extractor.