Engrama

Graph-based long-term memory framework for AI agents.

Engrama gives any AI agent persistent, structured memory backed by a
knowledge graph. Instead of flat key-value stores or opaque vector
databases, Engrama stores entities, observations, and
relationships — and lets agents traverse that graph to reason about
their accumulated knowledge.

Two backends are first-class:

SQLite + sqlite-vec (default since 0.9) — single file, zero
external services, pip install engrama and you're running.
Neo4j 5.26 LTS (opt-in) — for multi-process production setups,
large-scale vector search, or teams that already use Cypher.

The data model is identical on both. See docs/backends.md
for a full decision guide; the rest of this README assumes the SQLite
default.

Since 0.13.0, every node and relation is owned by an
(org_id, user_id) identity and reads are fail-closed: a missing or
partial scope matches nothing rather than falling back to "see all". A
single-process install runs as one stable standalone identity and needs
no configuration; a multi-tenant deployment supplies the identity per
request from an authenticating gateway. See
docs/security.md.

Inspired by Karpathy's second-brain concept, but built for agents
instead of humans — and with graphs instead of wikis.

Why graphs?

	Flat JSON / KV	Vector DB	Engrama (Graph)
Relationship queries	❌	❌	✅ native
Scales to 10k+ memories	❌ slow	✅	✅
Works without embeddings	✅	❌	✅ (optional)
Local-first / private	✅	depends	✅
Zero external services	✅	❌	✅ (SQLite)
"What projects use FastMCP?"	full scan	approximate	1-hop traversal

Prerequisites

You need two things to run on the default SQLite backend. Docker is
not required unless you opt into Neo4j.

Requirement	Version	How to check	Install guide
Python	3.11 or newer	`python --version`	python.org/downloads
uv (Python package manager)	any recent	`uv --version`	docs.astral.sh/uv

Windows users: after installing Python, make sure "Add Python to
PATH" is checked. After installing uv, you may need to restart your
terminal.

Optional:

Obsidian — for vault sync features.
A local embedder for semantic search.
Docker Desktop —
only if you opt into the Neo4j backend.

Quick start (SQLite, zero-dep)

Step 1: Install

From PyPI (recommended):

pip install engrama          # or: uv add engrama

Or from source, for development:

git clone https://github.com/scops/engrama
cd engrama
uv sync

The commands below assume a PyPI install (engrama ...). From a source
checkout, prefix each one with uv run (uv run engrama ...).

Step 2: Initialise the schema

engrama init --profile developer

Step 3: Verify

engrama verify

Step 4: Use it

A) From Python:

from engrama import Engrama

with Engrama() as eng:
    eng.remember("Technology", "FastAPI", "High-performance async framework")
    eng.associate("MyProject", "Project", "USES", "FastAPI", "Technology")
    results = eng.search("microservices")

B) From the command line:

engrama search "FastAPI"
engrama reflect

Quick start (Neo4j, opt-in)

If you need multi-process writes, very large vector indexes, or an existing Cypher toolchain, install with the Neo4j extra:

pip install "engrama[neo4j]"     # or, from source: uv sync --extra neo4j

Configure your credentials by copying .env.example to .env and setting GRAPH_BACKEND=neo4j. Start Neo4j with docker compose up -d, and then initialize the schema:

engrama init --profile developer
engrama verify

📚 Full Documentation

All further details, including MCP integration (Claude Desktop), Obsidian sync, Architecture, and the complete API Reference, are available in the official documentation.

👉 Read the Full Documentation