Engram

Engram is a distributed memory system for LLM agents, written in Rust. It stores short-term messages, long-term vector memories, and pinned facts per session, then assembles them into a context window on request. Every write goes through Raft consensus across a three-node cluster, so the system survives node loss without manual intervention.

It also does things most agents handle themselves: summarizing old messages before they crowd the context, extracting entities and relationships into a per-session knowledge graph, reconstructing past state at any timestamp or checkpoint, and reranking retrieval results based on feedback. Generation stays outside. Engram handles the memory.

run it

Prerequisites: Rust 1.92+, Docker, OpenAI API key.

git clone https://github.com/bit2swaz/engram.git
cd engram
docker run -d --name engram-redis -p 6379:6379 redis:7-alpine
export OPENAI_API_KEY=sk-your-key-here
export REDIS_URL=redis://localhost:6379
cargo run

Or with Docker Compose (single node):

cp .env.example .env
docker compose up -d

Or as a three-node cluster:

cp .env.example .env
docker compose -f docker-compose.cluster.yml up -d --build
./scripts/cluster-init.sh
./scripts/cluster-verify.sh

examples

# create a session
curl -X POST http://localhost:3000/sessions

# add a message
curl -X POST http://localhost:3000/sessions/{id}/messages \
  -H 'content-type: application/json' \
  -d '{"role":"user","content":"what is ownership in rust?"}'

# get assembled context for the agent's next turn
# response includes a query_id you can use for feedback
curl http://localhost:3000/sessions/{id}/context

# tell engram which retrieval was useful
curl -X POST http://localhost:3000/sessions/{id}/feedback \
  -H 'content-type: application/json' \
  -d '{"query_id":"<query_id from context response>","outcome":"positive"}'

# semantic search
curl -X POST http://localhost:3000/sessions/{id}/search \
  -H 'content-type: application/json' \
  -d '{"query":"rust ownership","top_k":5}'

# see what the session looked like at a past point
curl 'http://localhost:3000/sessions/{id}/at?at=2025-01-15T12:00:00Z'

# diff two points in time
curl 'http://localhost:3000/sessions/{id}/diff?from=10&to=50'

docs

• API.md — every endpoint, request/response shapes, error codes
• ARCHITECTURE.md — component diagram, design decisions, how the pieces fit
• SSOT.md — data models, invariants, the authoritative spec for the whole system
• QUALITY_BENCHMARKS.md — LongMemEval and BEAM benchmark runbook
• COMPARISON.md — how Engram compares to other memory systems
• CONTRIBUTING.md — how to build, test, and contribute

license

MIT. See LICENSE.