Engraphy — Developer Documentation

Engraphy is a self-hosted memory engine for AI agents: a typed knowledge graph on Postgres + pgvector, with embedding-native deduplication, hybrid (semantic + lexical) retrieval, real graph traversal, multi-principal isolation enforced in the database, and a schema ("pack") system that lets one engine serve many differently-shaped memory applications.

It is built to replace the flat-JSON / stdio / single-user reference MCP memory server with something that survives concurrency, distance, duplicates, and years.

Naming. The product is Engraphy. The code module, Python package, CLI, environment variables, and database identifiers are all still named engram (import engram, engram-admin, ENGRAM_DATABASE_URL, the Server("engram") MCP name). This documentation uses Engraphy for the product and engram when naming the actual code you type.

What Engraphy gives you

A typed memory graph. Memories are typed nodes (a fact, an event, a person, a decision, …) connected by typed edges (involves, references, same_topic, supersedes, …). Types, their attribute schemas, and the edge rules between them are declared per space in a pack.
Writes that dedup themselves. Every write is embedded and banded against existing memory: a near-verbatim restatement auto-merges, a genuinely new but related fact is merge-linked (kept as its own searchable node, joined by a same_topic edge — nothing is silently absorbed), and a borderline case parks as a pending duplicate-check verdict for the caller to resolve.
Hybrid retrieval. search fuses a vector leg (cosine over embeddings) and a lexical leg (Postgres full-text) with Reciprocal Rank Fusion, then walks edges with traverse. Attribute content is embedded into the searchable surface, so a fact stored only in a typed attribute is still findable.
Multi-space, multi-principal isolation enforced by Postgres Row-Level Security — not by application checks that can be forgotten.
An operator CLI and an MCP tool surface for everything from bootstrapping a space to minting tokens, importing data, and verifying restores.

Read in this order

#	Doc	For
1	Architecture overview	Understanding the memory model, the write path, the read path, and the core invariants.
2	Setup & install	Getting Postgres + pgvector up, running migrations, and serving the MCP endpoint locally end-to-end.
3	Build your own pack	Declaring node types, edge types, attribute schemas, the `searchable` attr flag, dedup thresholds, and applying a pack. Includes a complete worked example.
4	Tool / API reference	Every MCP tool a developer calls, with parameters, returns, and a realistic example each.
5	Deployment guide	Running Engraphy as a service, auth/scopes, backups, and the admin CLI.
6	End-to-end tutorial	Build a real app on Engraphy: ingest data through the dedup pipeline, then query it.

Requirements at a glance

Postgres 16 with the pgvector extension (the pgvector/pgvector:pg16 image ships both).
Python ≥ 3.12.
dbmate on PATH for migrations.
The embedding model nomic-ai/nomic-embed-text-v1.5 (384-dim, downloaded on first boot, ~523 MB, cached).

See Setup for the exact steps.