Engram — Graph-Based Memory for AI Agents

Engram is a memory system that gives AI agents persistent, searchable memory across conversations. It extracts memories from session transcripts, stores them in a graph database, and provides graph-aware search with spreading activation, transcript search, and optional cross-encoder re-ranking.

Zero external dependencies. Pure Python stdlib. SQLite for storage. Works with any OpenClaw agent.

Quick Start

1. Install

pip install openclaw-engram

Or from source:

git clone https://github.com/alder-ai/engram
cd engram
pip install -e .

2. Configure

Create engram.json in your agent's workspace:

{
  "db_path": "engram.db",
  "session_dir": "/path/to/your/sessions"
}

Set API keys:

export ANTHROPIC_API_KEY="sk-ant-..."    # Required — powers the encoder
export OPENAI_API_KEY="sk-..."           # Recommended — powers embeddings

Key	Required?	What breaks without it
ANTHROPIC_API_KEY	Yes	Encoder cannot run, no memories extracted
OPENAI_API_KEY	No	No embeddings, search degrades to keyword-only. Use Ollama as free alternative.

3. Register as MCP Server

Add to your mcporter.json:

{
  "mcpServers": {
    "engram": {
      "command": "python3",
      "args": ["-m", "engram.mcp", "--workspace", "/path/to/workspace"]
    }
  }
}

4. Seed (recommended)

For instant results, process your existing session history:

python3 scripts/engram-backfill.py --workspace /path/to/workspace --full

Without seeding, search becomes useful after ~10 conversations (~2-4 hours of agent activity).

5. Set Up Crons

Engram runs as background cron jobs:

# Encoder — checks for new sessions every 2 minutes
*/2 * * * * python3 scripts/engram-trigger.py --workspace /path/to/workspace

# Renderer — regenerates MEMORY.md every 10 minutes
*/10 * * * * python3 scripts/engram-render.py --workspace /path/to/workspace

# Archivist — graph hygiene + transcript indexing every 30 minutes
*/30 * * * * python3 scripts/engram-archivist.py --workspace /path/to/workspace

# Consolidator — nightly dedup + promotion (uses Opus)
0 3 * * * python3 scripts/engram-consolidator.py --workspace /path/to/workspace

How It Works

Engram has a 4-tier architecture:

1. Encoder (Sonnet, every 2 min) — Reads session transcripts, extracts memories and facts via LLM, generates embeddings, stores as draft nodes in the graph
2. Archivist (Haiku, every 30 min) — Graph hygiene: conflict detection, accuracy spot-checks, embedding backfill, transcript indexing
3. Renderer (no LLM, every 10 min) — Generates MEMORY.md from the graph using prominence-based ranking with importance decay
4. Consolidator (Opus, nightly) — Deduplicates drafts, processes review queue, promotes knowledge to workspace files, activates draft nodes

Search

Agents search memory via MCP:

mcporter call engram.search query="project deployment status"
mcporter call engram.search query="user preferences" top_k=20 expand=true
mcporter call engram.search query="budget figures" rerank=true

Search Pipeline

1. Seed selection — Embedding similarity (0.7) + keyword match (0.3), topic boost, prominence weighting
2. Spreading activation — 2-hop graph traversal through co-occurrence edges
3. Reranking — Blend activation score (0.6) with direct relevance (0.4)
4. Transcript search — FTS5 BM25 + semantic search over raw conversation archives
5. Result merge — Percentile normalization, node results rank above transcript results
6. Cross-encoder (opt-in) — Haiku re-scores top candidates for precision
7. Query expansion — Keyword augmentation + LLM reformulation for sparse results

Features

• Graph-aware: Spreading activation discovers related memories through co-occurrence edges
• Transcript search: Raw conversation archives indexed with FTS5 + embeddings — catches what the encoder missed
• Cross-encoder re-ranking: Opt-in Haiku-based precision scoring (rerank=true)
• Query expansion: Always-on keyword augmentation (numbers, possessives) + LLM expansion for sparse results
• Multi-resolution: Three detail levels (atomic → moderate → full) selected by relevance score
• Importance decay: Memories fade over time based on importance level, with access-based renewal

Configuration

See examples/ for full configuration options:

• engram.json.minimal — Just the essentials
• engram.json.full — All options documented
• engram.json.ollama — Local-only setup (no paid APIs for embeddings)

Cost

Default daily cost: ~$0.80-$3.00/day depending on activity. Daily cap: $5.00 (configurable).

See docs/COST-GUIDE.md for detailed breakdown and cost reduction strategies.

Platform

macOS and Linux. Windows is not currently supported (uses fcntl for file locking).

Documentation

• Technical Reference — Full architecture, algorithms, schema, and API documentation
• Session Format — Expected session JSONL schema
• Cost Guide — Running cost estimates and optimization
• Security — Data storage, secret scanning, API key handling

License

MIT