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. Each identity can permanently erase its own memory through the engrama_gdpr_forget tool (GDPR right-to-erasure). 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

---

Security considerations

Engrama stores everything an agent learns, so treat the memory graph as sensitive data. The full policy lives in docs/security.md; the essentials:

• Data residency. On the default SQLite backend all data lives in a single local file (~/.engrama/engrama.db by default) — nothing leaves your machine. It is plain SQLite: keep it off shared filesystems, back it up, and rely on filesystem permissions for at-rest protection. On the Neo4j backend, data resides wherever you host Neo4j; you own that deployment and its region.
• Neo4j authentication. Supply credentials through .env / environment variables (NEO4J_URI, NEO4J_USERNAME, NEO4J_PASSWORD) — never commit them. The shipped docker-compose.yml is for local dev; change the default password and enable TLS before any networked use.
• Embedding providers. Endpoints reached via OPENAI_BASE_URL should use HTTPS unless they are on localhost or a trusted network. With EMBEDDING_PROVIDER=none no text is sent anywhere; search degrades to fulltext-only.
• Tenant isolation. Since 0.13.0 every node and relation is owned by an (org_id, user_id) identity and reads are fail-closed. A single install runs as one stable standalone identity; a multi-tenant deployment must inject the identity per request from an authenticating gateway (set ENGRAMA_REQUIRE_IDENTITY=1 to fail closed on missing headers). See docs/security.md.
• Right to erasure. Each identity can permanently erase its own memory via the engrama_gdpr_forget tool (GDPR). There is no undo and no server-side backup.
• Network exposure. The MCP server is meant for a local client. The optional Streamable HTTP transport ships without authentication — keep it on loopback or behind your own authenticated gateway.

---

📚 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