Engraphis

Full Engraphis install: pip install "engraphis](https://github.com/Coding-Dev-Tools/engraphis/blob/main/BENCHMARKS.md)[all]"

The completeengraphis[all]install is the default way to use Engraphis: it includes the local dashboard, Smart MCP server, documents, Cloud Sync client, and supported optional integrations. Python 3.10+ is required.

pip install "engraphis[all]" engraphis-dashboard

The dashboard opens athttp://127.0.0.1:8700. Local memory needs no account or API key.

For MCP clients other than Codex, configure a stdio server whose command isengraphis-mcp; see theagent connection guide.

Useengraphis-updateto upgrade the installation using its detected install method. Package metadata does not record which extras were selected, so the updater defaults to the safe supersetengraphis[all]rather than silently dropping an optional surface. For a deliberate selection, setENGRAPHIS_UPDATE_EXTRASto a comma-separated list (for exampleserver,mcp), or set it tononefor the base package only.

Upgrading to 1.4:engraphis-mcpnow exposes the nine-tool Smart gateway. Integrations that require the former 34 direct tool names should runengraphis-mcp-classic. The SQLite schema in the 1.4.0 release was version 9. Existing v7-to-v8 databases already containconfidenceandpinned_at/unpinned_at; v9 adds thememory_tombstonesrepository-scope column/table and performs a one-time entity-canonicalization repair, then migrates automatically on first open. A tombstone with a knownrepo_idis terminal only in that repository; legacy repo-less tombstones remain global. See the1.4.0 release notes.

Upgrading to 1.5:schema 10 bounds legacy retention state and schema 11 backfills explicit approval only for eligible pre-review local memories. Pending and quarantined evidence remains gated. Existing 1.4.x databases migrate automatically when Engraphis 1.5 opens them; see the1.5 release notes.

Upgrading to 1.6:existing 1.5 databases migrate automatically through schema 12, which classifies content-free erasure markers before sync: existing markers become local-onlynever_export, while new secure erasures becomeremote_erasureonly for non-secretworkspace/reporecords already eligible for sharing. Schema 13 adds per-memory hybrid logical clocks for deterministic descriptive-state sync and durable, content-free proof that a memory crossed a sync boundary. Schema 14 adds the Obsidian collection and import manifests; schema 15 generalizes them to source-neutral local documents, preserves temporal source lineage across re-imports, binds adapters and target scopes, and retains only bounded, content-free per-job format/result metadata. The schema 16 migration persists each import job's optional session target and requires source lineage and job-item attachments to remain in that exact session. See the1.6 release notes.

The core task is continuity: retrieve the current, supported project decision without dragging the whole history into the next prompt. Seemeasured token and context savingsfor the short version of how much less history an agent has to carry.

Inspect memories, supersession diffs, recall scores, timelines, links, consolidation, and audit records in the dashboard. The offline graph renderer is vendored, and the interface is keyboard- navigable with light and dark themes. Graph exploration offers a focusedHigh qualityview and an explicit worker-backedShow all nodesview for complete entity projections up to 20,000 nodes and 200,000 relationships; see thegraph performance profiles.

The memory engine, embeddings, conflict resolution, and recall stay local without an LLM. An explicitly configured provider adds structured extraction, cited synthesis, consolidation, and retention supervision. Configure it inSettings → Connect an LLM. The activity view records outcomes, never keys, prompts, or raw provider responses. See theLLM provider guidefor setup and privacy choices.

Choose and configure an external LLM with theLLM provider guide, including OpenAI, Anthropic, Google, OpenRouter, Ollama, Cohere Command, Command Code Provider, and other compatible endpoints. The guide also covers Codex subscription MCP connections.

pip install "engraphis[all]" # self-hosted dashboard, MCP, code graph, documents, transcription, PostgreSQL, and Cloud Sync pip install "engraphis[server]" # dashboard + REST API pip install "engraphis[mcp]" # MCP server only pip install "engraphis[documents]" # PDF + image OCR bindings pip install "engraphis[transcription]" # faster-whisper audio/video pip install "engraphis[postgres]" # PostgreSQL schema introspection pip install "engraphis[code]" # tree-sitter code graph indexing pip install "engraphis[vector]" # native sqlite-vec exact-KNN acceleration pip install "engraphis[cloud-sync]" # Cloud Sync client crypto/runtime pip install "engraphis[encryption]" # SQLCipher encryption-at-rest extra pip install engraphis # core library: numpy only, fully offline

The official Docker image includes the local Tesseract executable for image OCR. Outside Docker, thedocumentsextra installs its Python bindings; install Tesseract through your operating system as well if you enable image OCR.

The NumPy-only core library supports Python 3.9+. Current patched releases of the WebUI stack, MCP SDK, image parser, and Cloud Sync client require Python 3.10+, so use Python 3.10 or newer for theserver,mcp,documents,cloud-sync, orallinstallation paths.

The defaultNumpyVectorIndexperforms an exact full scan. There is no universal memory-count cutoff because latency depends on vector size, hardware, filters, and the rest of the recall pipeline. Measure your machine withpython -m eval.vector_scale --backend numpy, then runpython -m eval.performanceon a representative corpus. If exact scans miss your latency target, installengraphis[vector], create the engine withvector_backend="sqlite-vec", and remeasure. The stable sqlite-vecvec0backend executes exact KNN in native code; it is acceleration, not a claim of sublinear ANN scaling. SeeBENCHMARKS.mdfor the reproducible commands and reporting limits.

sqlcipher3-binarypublishes CPython manylinux x86-64 wheels. On that target,engraphis[encryption]installs the driver. The cross-platformallextra deliberately omits it soallremains resolvable on macOS, Windows, Linux ARM, and musl; on those targets, provision a compatible SQLCipher driver separately before enabling a database key. The programmatic core remains plaintext unless a database key is configured. For a fresh database,engraphis-initenables SQLCipher automatically when a compatible driver is available, creates a private key sidecar, and can be overridden with--no-encryption.

Linux / macOS:ifpip installfails witherror: externally-managed-environment, your system Python is marked read-only (PEP 668). Install into a virtual environment instead. Runpython3 -m venv venv && source venv/bin/activate && pip install "engraphis[server]"Alternatively, use Docker (docker compose up).pipx install "engraphis[server]"also works.

First run downloadsall-MiniLM-L6-v2(~80 MB). Without it, the engine falls back to deterministic feature hashing so it always runs offline. That fallback captures lexical overlap, not meaning: recall and grounded MCP responses setdegraded_mode=trueandsemantic_support=false, and disable vector retrieval plus semantic-cosine evidence. Install a declared embedding model for semantic retrieval.

To require a model that is already local, setENGRAPHIS_EMBED_MODEL=local:/absolute/model/pathorlocal:<cached-model-id>. This path never downloads a model. If it is unavailable, Engraphis explicitly enters lexical degraded mode instead of presenting hash-vector scores as semantic.

pip install "engraphis[server]" engraphis-dashboard # → http://127.0.0.1:8700 engraphis-dashboard --install-shortcuts # → Desktop + Start Menu icons

docker compose up # → http://127.0.0.1:8700

For Docker Compose persistence and loopback-port configuration, see theDocker deployment guide.engraphis-serverandengraphis serverare headless compatibility aliases for this same v2 service, so every public surface has the same scoped recall and retention model.

For optional LAN exposure, token configuration, and HTTP MCP setup, see the[Docker deployment guide.

SetENGRAPHIS_API_TOKENto require API authentication andENGRAPHIS_DB_KEYto encrypt the local database at rest. Hosted-plan credentials configure customer clients; they do not install premium server implementations into this image. Seedocker-compose.ymlfor options.