https://engraphis.com/

https://discord.com/invite/Wfr2ejBmY

Give your AI agents a memory. See it, search it, and maintain it, all in a beautiful WebUI on your own machine.

^{Knowledge Graph · run engraphis-dashboard to see it live}

Open-core boundary: this repository contains the free local engine, dashboard, MCP server, and customer-side clients. Hosted sync, analytics, automation, and team services run on the official hosted service; their server implementations are not distributed here.

Support continued Engraphis development with Pro. Start a 3-day Pro trial or subscribe to Pro.

^{Less repeated history means more room for the task, tools, and useful evidence.}

python -m eval.harness --dataset eval/datasets/codemem.jsonl --k 5
python -m eval.grounded
python -m eval.chunking_eval
python -m eval.performance --dataset eval/datasets/codemem.jsonl --k 5 --iterations 10 --json
python -m eval.productivity --dataset eval/datasets/codemem.jsonl

The complete engraphis[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 at http://127.0.0.1:8700. Local memory needs no account or API key.

Use a smaller package only when you intentionally need a limited surface. The NumPy-only core continues to support Python 3.9+.

For MCP clients other than Codex, configure a stdio server whose command is engraphis-mcp; see the agent connection guide.

Upgrading to 1.4: engraphis-mcp now exposes the six-tool Smart gateway. Integrations that require the former 33 direct tool names should run engraphis-mcp-classic. The SQLite schema remains version 7, so this MCP surface change does not require a data migration. See the 1.4.0 release notes.

An agent should not have to reconstruct a project from scattered chat history on every task. Engraphis turns local project knowledge into scoped, time-aware memory; retrieves the evidence that supports the current question; and returns a bounded, attributable context packet.

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

The Engraphis dashboard opens http://127.0.0.1:8700. Local memory needs no cloud account, signup, or API key and stays in a SQLite file on your machine.

Ledger is the primary local interface for recall, memories, graph exploration, provenance, workspaces, and manual consolidation. Classic preserves the former full tool suite; both use the same local data. Switch in Manage → Settings → Interface (Ledger) or Settings → Appearance & Engine (Classic).

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.

Engraphis gives agents durable, scoped, explainable project knowledge. The local engine combines Ebbinghaus decay, bi-temporal facts, and hybrid vector/lexical/graph recall; it runs offline with SQLite, local embeddings, and numpy only.

• Grounded and governed: deterministic conflict resolution, cited answers or abstention, explicit correction/promotion/forgetting, and a complete history.
• Agent-ready: MCP tools, hard-budget context packets, handoffs, and code-aware retrieval.
• Auditable: content-free receipt chains, provenance, and temporal/entity/code relationships.
• Practical: local file and code ingest, optional PDF/OCR/transcription, and SQLCipher at rest.

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 in Settings → Connect an LLM. The activity view records outcomes, never keys, prompts, or raw provider responses. See the LLM provider guide for setup and privacy choices.

Privacy boundary: text sent to an explicitly selected provider leaves the local process under that provider's terms. Use ENGRAPHIS_RETENTION_SUPERVISOR=none (the default) and the offline chunk extractor when ingestion must remain entirely local.

Choose and configure an external LLM with the LLM provider guide, including OpenAI, Anthropic, Google, OpenRouter, Ollama, Cohere Command, Command Code, and compatible endpoints.

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[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, the documents extra 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 the server, mcp, documents, cloud-sync, or all installation paths.

The default NumpyVectorIndex performs 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 with python -m eval.vector_scale, then run python -m eval.performance on a representative corpus. If exact scans miss your latency target, create the engine with vector_backend="sqlite-vec" and remeasure. See BENCHMARKS.md for the reproducible commands and reporting limits.

sqlcipher3-binary publishes CPython manylinux x86-64 wheels. On that target, engraphis[encryption] installs the driver. The cross-platform all extra deliberately omits it so all remains resolvable on macOS, Windows, Linux ARM, and musl; on those targets, provision a compatible SQLCipher driver separately before enabling a database key. Plaintext SQLite remains the explicit default on every platform.

Linux / macOS: if pip install fails with error: externally-managed-environment, your system Python is marked read-only (PEP 668). Install into a virtual environment instead. Run python3 -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 downloads all-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 set degraded_mode=true and semantic_support=false, and disable vector retrieval plus semantic-cosine evidence. Install a declared embedding model for semantic retrieval.

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 the Docker deployment guide. engraphis-server and engraphis server are 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.

Set ENGRAPHIS_API_TOKEN to require API authentication and ENGRAPHIS_DB_KEY to encrypt the local database at rest. Hosted-plan credentials configure customer clients; they do not install premium server implementations into this image. See docker-compose.yml for options.

pip install "engraphis[mcp]"
engraphis-init                     # writes .env + prints config snippets
claude mcp add engraphis -- engraphis-mcp
cmd mcp add engraphis -- engraphis-mcp  # Command Code CLI

For Command Code scopes, verification, and its optional Provider API setup, see the Command Code section of the LLM provider guide.

engraphis-mcp is zero-configuration Smart MCP: agents begin with six compact tools for sessions, prompt-ready recall, durable memory, action discovery, and safe execution. For code graphs, governance, audit, or other advanced work, the agent calls engraphis_discover_actions and then the indicated read or action executor; no profile selection is required. The gateway validates the discovered capability again before it runs it, and clients remain responsible for their normal destructive-action approval boundary.

Existing clients that pin the historical 33 named tools can use engraphis-mcp-classic (or engraphis-mcp-http --classic). The complete classic inventory, including engraphis_check_update, is in the MCP tool reference.

For installation, configuration, lifecycle commands, and the local trust boundary, see the Pi extension guide.

pip install "engraphis[code]"
engraphis-graph index -w acme -r api --root .
engraphis-graph search -w acme -r api "UserService"
# `query`/`explain` blend code search with your stored memories: query matches symbol
# and file NAMES (a full question sentence won't match anything), and explain's answer
# is drawn from memories recorded against the repo; both are empty on a fresh index.
engraphis-graph query -w acme -r api "UserService"
engraphis-graph explain -w acme -r api "why does deploy depend on approval?"
engraphis-graph path -w acme -r api UserService DatabasePool
engraphis-graph impact -w acme -r api --root . --git-range origin/main...HEAD
engraphis-graph prs -w acme -r api --base main --head HEAD
engraphis-graph export -w acme -r api -o engraphis-graph-out
engraphis-graph install-merge-driver --root .

The export contains graph.json, a self-contained graph.html, and GRAPH_REPORT.md. Indexing supports Python, JavaScript, TypeScript, Go, Rust, Java, C#, C, C++, SQL, and Terraform. Tree-sitter is used when available; the dependency-free regex backend remains a functional fallback. Definitions, methods, calls, imports, ownership, variables, inheritance/implementation, and docstrings/comments are indexed. Indexing is incremental by content hash, honors .engraphisignore, and does not follow file symlinks outside the repository root. Call edges are name-based and best-effort rather than type-resolved. The optional Git merge driver validates bounded graph JSON and deterministically unions nodes and edges instead of choosing one export side.

For a read-only recall and graph API that can be shared without exposing write operations:

pip install "engraphis[server]"
engraphis-graph-server                 # API at http://127.0.0.1:8720; schema at /openapi.json

A non-loopback bind fails closed unless ENGRAPHIS_GRAPH_TOKEN (or ENGRAPHIS_API_TOKEN) is set. See the v3 architecture/design document.

from engraphis.service import MemoryService

mem = MemoryService.create("engraphis.db")
mem.remember("Auth migrated from JWT to PASETO.", workspace="acme", repo="api")
hit = mem.recall("why did we change auth?", workspace="acme", repo="api")
print(hit["context"])

The same MemoryService backs the dashboard and the MCP server.

Agent hosts can avoid retrieval when their existing history already fits:

decision = mem.adaptive_context(
    "what should the agent do next?",
    current_history,
    workspace="acme",
    repo="api",
    max_context_tokens=8_192,
    retrieval_token_budget=1_024,
)
prompt_context = decision["context"]

The decision is history_bypass when the history fits, retrieval when compact evidence is strong, and history_fallback when weak retrieval should widen back to recent raw history.

For an agent prompt, prefer engraphis_recall_context: it returns one hard-budget packed context plus compact sources, deterministic usage accounting (budget_tokens, context_tokens, source_tokens, saved_tokens, savings_ratio, packed_count, omitted_count, and token_counter), and optional diagnostics. Accounting is exact for the named counter; inject the reader's tokenizer when reader-model token parity is required. engraphis_recall remains the compatible full-recall surface; use response_mode="compact" when the packed context is enough and full memory bodies would duplicate it. For advanced query-planning configuration, see the architecture guide.

For bi-temporal reads, valid_at selects what was true at a Unix timestamp and known_at selects what Engraphis had learned then. as_of remains a compatibility alias for valid_at; supplying both is allowed only when they match.

For a mutable claim, pass a stable subject_key and optional claim_kind, such as subject_key="api.rate_limit", claim_kind="configured_value". Offline conflict resolution deterministically adds, reinforces, relates, or supersedes records while preserving temporal history; it does not need an LLM. Matching claim identities let it supersede substantially reworded mutable facts. Without them, the dependency-free lexical embedder cannot reliably infer that a paraphrase is a contradiction, so keep both records or use an explicit correct operation.

Engraphis separates automatic write resolution from explicit human governance:

Manual N→1 merge is available through MemoryService.merge() and POST /api/merge:

a = mem.remember("Deploys happen Friday at 3pm.", workspace="acme")
b = mem.remember("We deploy Fridays around 15:00.", workspace="acme")

merged = mem.merge(
    [a["id"], b["id"]],
    "Deploys ship every Friday at approximately 15:00.",
    workspace="acme",
    reason="deduplicate the deployment schedule",
)
print(merged["compaction"])

retire is intentionally not deletion: it preserves temporal history, FTS, and vector evidence for historical reads. If a credential was captured, new writes are blocked before storage; for a legacy leak use the explicitly destructive MemoryService.secure_erase() or POST /api/secure-erase/engraphis_secure_erase. That flow removes the one memory and local FTS/vector/ANN and derived graph/link rows, runs SQLite secure-delete, WAL checkpoint, and VACUUM, and scans recognised local SQLite recovery backups. It cannot erase exports, filesystem snapshots, remote peers, unknown backups, or information a running/compromised agent already read; rotate the credential. See secure-erasure limits. forget remains a deprecated compatibility alias for retire.

All sources must belong to the named workspace. The result inherits the strictest source sensitivity, remains untrusted if any source was untrusted, and stays pinned if any source was pinned. The full multi-predecessor chain remains visible through inspection, Why, and Timeline.

The core engine, local dashboard, MCP server, and manual consolidation are Apache-2.0 and free. Pro and Team are services that provide optional access to the official hosted service; its control-plane, billing, relay, compute, and Team identity modules live in a private repository. They do not limit the local core. See hosted plans, licensing, and Cloud Sync for service boundaries, lifecycle, and pricing.

Subscribe to Pro to support the project and add hosted services.

Compare hosted plans when you are ready to evaluate the service boundary and billing options.

Engraphis exposes a zero-configuration Smart MCP gateway plus a 33-tool Classic compatibility server across memory, recall, code graphs, governance, sessions, and privacy-safe audit receipts. The focused MCP tool reference is the source for the full inventory and parameters.

Memory, entity, and code relationships live in one local graph. Engraphis also provides content-free operation receipts for inspectable audit evidence. See the architecture, MCP tool reference, and security policy for the data model, tools, and guarantees.

Cloud Sync is an optional hosted Pro/Team service. The public package includes the customer client and deterministic merge implementation; hosted relay and account operations are separate. See Cloud Sync for setup, encryption, merge behavior, and the local folder exchange.

Engraphis is local-first and binds to loopback by default. Read the security policy before remote deployment or integrating external resources; it covers supported versions, data protections, threat model, and vulnerability reporting.

Set ENGRAPHIS_DB_KEY (or ENGRAPHIS_DB_KEY_FILE) and install the extra:

pip install "engraphis[encryption]"

The entire main memory database file is transparently encrypted with AES-256 via SQLCipher; full-text search, the graph, and every query keep working unchanged. Customer authentication and managed-service state use their respective deployment protections. When a key is set for the main database, Engraphis fails closed with an error rather than silently falling back to plaintext. Generate a strong key:

python -c "import secrets; print(secrets.token_hex(32))"

An existing plaintext database cannot be opened with a key: migrate it (dump → import into a fresh keyed DB). See .env.example for all encryption options.

Import supported documents and code through the dashboard, a local folder, or MCP. Optional extractors add offline chunking, structured LLM extraction, document OCR, transcription, and PostgreSQL schema ingestion. See the MCP tool reference, architecture guide, and security policy for formats, configuration, and local-resource safeguards.

Manual consolidation is free, local, and dry-run by default; use the dashboard, SDK, CLI, or MCP. Hosted Pro and Team automation is optional managed compute that produces reviewable proposals rather than silently changing local data. See hosted plans, licensing, and the MCP tool reference for scope and use.

All via environment (or .env):

See .env.example for the full customer-runtime and managed-service client options.

engraphis/
├── engraphis/
│   ├── core/                # v2 engine: interfaces, store, recall, scoring, schema, sync
│   ├── backends/            # pluggable embedder / vector index / reranker / codegraph / sync transports / encryption
│   ├── service.py           # validated MemoryService facade
│   ├── mcp_server.py        # Smart MCP gateway + 33-tool Classic compatibility server
│   ├── dashboard_app.py     # dashboard WebUI (FastAPI)
│   ├── dashboard_assets/    # primary Ledger interface + graph engine
│   ├── classic_assets/      # selectable full operator dashboard backup
│   ├── read_only_api.py     # token-protected recall/repository-graph HTTP surface
│   ├── hosted_client.py     # hosted URLs, plan labels, and endpoint validation only
│   ├── licensing.py         # compatibility facade for hosted presentation metadata
│   ├── cloud_session.py     # rotating hosted customer-session client
│   ├── cloud_features.py    # consented managed-feature protocol client
│   ├── config.py / app.py   # env settings / REST server
│   └── static/              # compatibility dashboard asset paths
├── eval/                    # offline retrieval eval harness + datasets
├── tests/                   # offline-first pytest suite and release/security contracts
├── scripts/                 # dashboard, server, graph, CLI, connect, update, consolidation, sync
├── docs/                    # product, API, hosting, sync, and provider guides
├── Dockerfile / docker-compose.yml
└── pyproject.toml

New capability belongs in the v2 path (engraphis/core/, engraphis/backends/, and MemoryService) behind the interfaces in core/interfaces.py. The flat-namespace v1 server under engraphis/app.py, routes/, stores/, and engines/ remains a compatibility/reference surface; engraphis-dashboard, the MCP server, and the Python quickstart above use v2.

Apache-2.0. See LICENSE and NOTICE. "Engraphis" is a trademark of the Engraphis project; the license does not grant trademark rights. Code already distributed under Apache-2.0 keeps that grant; later releases cannot retroactively withdraw it. The official hosted control plane, its production credentials and records, managed operations, support, and future separately delivered commercial modules are outside the public source grant. See docs/LICENSING.md for the complete boundary.