Metadata-Version: 2.4
Name: engram-causal
Version: 0.1.3
Summary: Causal memory for AI agents — not just what happened, why.
Author: Karan Kartikeya
Project-URL: Homepage, https://engram.viberank.co.in
Project-URL: Repository, https://github.com/karankartikeya/Engram
Project-URL: Documentation, https://engram.viberank.co.in/docs
Project-URL: Issues, https://github.com/karankartikeya/Engram/issues
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: fastapi
Requires-Dist: uvicorn[standard]
Requires-Dist: pydantic>=2.0
Requires-Dist: anthropic
Requires-Dist: kuzu
Requires-Dist: python-dotenv
Requires-Dist: httpx
Requires-Dist: datasets
Provides-Extra: hosted
Requires-Dist: boto3; extra == "hosted"
Requires-Dist: redis; extra == "hosted"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mypy; extra == "dev"

<p align="center">
  <strong>🔍 Engram</strong>
</p>

<p align="center">
  <a href="https://github.com/karankartikeya/engram/actions/workflows/ci.yml"><img src="https://github.com/karankartikeya/engram/actions/workflows/ci.yml/badge.svg" alt="CI"/></a>
  <a href="https://pypi.org/project/engram-causal/"><img src="https://img.shields.io/pypi/v/engram-causal" alt="PyPI"/></a>
  <a href="https://pepy.tech/project/engram-causal"><img src="https://static.pepy.tech/badge/engram-causal" alt="Downloads"/></a>
</p>

**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+

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

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

**BYOK (open-source, free):**
```bash
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):**
```bash
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

```bash
# 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](https://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.

## 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

```bash
engram serve --mcp

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

MCP tools: `why_query`, `store_triple`, `ingest_events`.

<details>
<summary>Contributing</summary>

**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.

</details>
