Engraphis

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.

Grounded, not guessed. Memory with receipts. Local by default.

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.

Measured token and context savings

Runtime estimator

The dashboard Overview and Audit/Receipts views also show a receipt-backed estimate from real context deliveries. It compares the host history or retrieved source baseline with the context Engraphis actually emitted, keeps token counters and release versions separate, and labels adaptive history reductions separately from packing savings. Receipts without estimator metadata remain historical/unclassified. This measures estimated prompt-context reduction; it does not measure provider billing. The /context-savings API and engraphis_context_savings MCP tool aggregate the complete history across all visible workspaces by default, or accept an explicit workspace plus optional from_ts, to_ts, and release_version filters.

Controlled before-and-after example

The chunked mode returns the relevant passage instead of the whole document: 526.0 fewer tokens per question. Under the same model-context budget, that leaves roughly 526 tokens for task instructions or other relevant evidence. This is evidence ID offline-chunking in the registered artifact below.

Measurement details and reproducibility

The table below contains every exact token/context aggregate currently published here and keeps its counting boundary explicit.

These values are evidence IDs offline-chunking and offline-performance in offline-fixtures-v9.json, SHA-256 455fc9d32a236e582a49aaaf9b84f30cae2573dc6ed982f4dd7dd845afcaf24c. BENCHMARKS.md records the matching suite digest, exact commands, and per-command config digests. External, model-dependent, consolidation, productivity, and latency results remain unpublished until the same evidence exists for them.

The compact payload shape avoids duplicating full memory bodies when the packed context and source list are enough. The evaluator tokenizes JSON-shaped full and compact payload proxies built from recall results; it does not serialize the MCP envelope or measure a transport response. The fixture therefore does not measure model-provider charges, end-to-end task time, or customer cost savings.

The measures are deliberately separate and must not be added together: chunking counts the content of retrieved memory records before ContextPacker, whereas compact recall counts a serialized JSON-shape payload proxy. “Tokens to evidence” is the size of the smallest retrieved memory record holding the reference evidence; it is not latency or end-to-end answer accuracy. Chunking creates more focused stored records, so this is a context-efficiency result, not a storage-reduction claim.

Reproduce the registered quality and token/context measurements without a network connection or API key:

bashCopy code
python -m eval.grounded
python -m eval.chunking_eval --dataset eval/datasets/longdoc.jsonl --k 5
python -m eval.performance --dataset eval/datasets/codemem.jsonl --k 5 --iterations 10 --json

These are small deterministic correctness and efficiency fixtures, not official LoCoMo / LongMemEval QA scores or a third-party leaderboard result. Compact-response counts use the exact engraphis.regex.v1 counter; the chunking evaluation uses its documented deterministic normalized-character estimator. Chunking measures retrieved memory content, while compact recall measures a serialized JSON-shape payload proxy, not an MCP transport response. See the registered artifact and BENCHMARKS.md for definitions, limitations, and canonical external-evaluation requirements.

Full Engraphis install: pip install "engraphis[all]"

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.

bashCopy code
pip install "engraphis[all]"
engraphis-dashboard

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

Smaller installation options

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.

Updating

Use engraphis-update to upgrade the installation using its detected install method. Package metadata does not record which extras were selected, so the updater defaults to the safe superset engraphis[all] rather than silently dropping an optional surface. For a deliberate selection, set ENGRAPHIS_UPDATE_EXTRAS to a comma-separated list (for example server,mcp), or set it to none for the base package only.

Upgrading to 1.4: engraphis-mcp now exposes the nine-tool Smart gateway. Integrations that require the former 35 direct tool names should run engraphis-mcp-classic. The SQLite schema in the 1.4.0 release was version 9. Existing v7-to-v8 databases already contain confidence and pinned_at/unpinned_at; v9 adds the memory_tombstones repository-scope column/table and performs a one-time entity-canonicalization repair, then migrates automatically on first open. A tombstone with a known repo_id is terminal only in that repository; legacy repo-less tombstones remain global. See the 1.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 the 1.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-only never_export, while new secure erasures become remote_erasure only for non-secret workspace/repo records 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 the 1.6 release notes.

What Engraphis gives an agent

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.

Dashboard and local UI

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).

Start it on every platform

In a source checkout, scripts/launch_dashboard.ps1 is only a Windows convenience wrapper. It delegates configuration, startup health, browser opening, and process lifecycle to the same engraphis-dashboard entrypoint rather than maintaining a second behavior path.

Accessibility-first inspection, built in

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 focused High quality view and an explicit worker-backed Every node view for complete entity projections up to 20,000 nodes and 200,000 relationships; see the graph performance profiles.

How it works

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.

Optional LLM providers

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 Provider, and other compatible endpoints. The guide also covers Codex subscription MCP connections.

Install

bashCopy code
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, 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 --backend numpy, then run python -m eval.performance on a representative corpus. If exact scans miss your latency target, install engraphis[vector], create the engine with vector_backend="sqlite-vec", and remeasure. The stable sqlite-vec vec0 backend executes exact KNN in native code; it is acceleration, not a claim of sublinear ANN scaling. See BENCHMARKS.md for the reproducible commands and reporting limits.

Dashboard, REST, and MCP entrypoints default to ENGRAPHIS_VECTOR_BACKEND=auto: they use sqlite-vec when the vector extra is installed and compatible, then safely fall back to NumPy. Programmatic MemoryEngine.create() and MemoryService.create() retain the deterministic numpy default unless a backend is requested explicitly. Use python -m eval.vector_scale --backend sqlite-vec for an input-identical direct-search comparison; setup/index-build time is explicitly excluded from the timed search envelope.

Persistent vectors fail closed unless the embedder can publish a durable, secret-free space fingerprint. Sentence Transformers use the loaded Hub commit or a manifest of local artifacts; when a remote model's immutable identity cannot be resolved, persistent vector recall remains gated instead of mixing spaces. For programmatic OpenAI-compatible embeddings, construct ApiEmbedder with an operator/provider space_version; without it the adapter remains usable for ephemeral embedding only. Its base_url may be a provider root or a /v1 root and is normalized to exactly one /v1/embeddings endpoint.

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. The programmatic core remains plaintext unless a database key is configured. For a fresh database, engraphis-init enables SQLCipher automatically when a compatible driver is available, creates a private key sidecar, and can be overridden with --no-encryption.

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.

To require a model that is already local, set ENGRAPHIS_EMBED_MODEL=local:/absolute/model/path or local:<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.

Quickstart: dashboard

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

Offline first run: the first launch downloads the all-MiniLM-L6-v2 embedding model (~80 MB), then runs fully offline. To stay offline-only, set ENGRAPHIS_EMBED_MODEL=local:/absolute/model/path (never downloads; unknown local models enter lexical degraded mode instead of faking semantic scores). Extraction defaults to ENGRAPHIS_EXTRACTOR=none (verbatim writes), the vector backend defaults to auto (native acceleration when installed, otherwise NumPy), and recall without a usable semantic space reports degraded_mode=true with lexical/graph recall. Run engraphis-init --check to verify the install, extras, and database writability.

Docker

bashCopy code
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.

Quickstart: MCP server (for coding agents)

bashCopy code
pip install "engraphis[mcp]"
engraphis-init                     # writes ~/.engraphis/config.env + prints config snippets
claude mcp add engraphis -- engraphis-mcp
codex mcp add engraphis -- engraphis-mcp  # Codex subscription

Offline first run: the first tool call lazily loads the all-MiniLM-L6-v2 embedding model (~80 MB, same download as the dashboard), then memory runs fully offline with no API key. To stay offline-only, set ENGRAPHIS_EMBED_MODEL=local:/absolute/model/path (never downloads); extraction defaults to ENGRAPHIS_EXTRACTOR=none, the vector backend auto falls back to NumPy without the vector extra, and recall without a usable semantic space reports degraded_mode=true with lexical/graph recall. Run engraphis-init --check to verify the install and database path before registering the server.

For Codex subscription setup and verification, see the agent connection guide and the LLM provider guide.

engraphis-mcp is zero-configuration Smart MCP: agents begin with nine compact tools for sessions, prompt-ready recall, durable memory, governed record read/update, conflict review, 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 35 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.

Pi extension

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

Command Code SessionStart hook

integrations/commandcode/ ships a SessionStart hook that warms up a new session with bounded, recalled context from the local Engraphis gateway. Fails open on timeout and is installed via python scripts/install_cc_hook.py.

prime-agent fleet

integrations/prime_agent/ ships a first-party Python package for PrimeIntellect prime-agent that exposes the same nine Smart MCP tools, with a PrimeAgentFleet of eight named sub-agents (researcher, planner, coder, reviewer, tester, documenter, monitor, integrator) sharing one engraphis-mcp stdio subprocess. Install via pip install ./integrations/prime_agent and register with python scripts/install_prime_agent.py. See the prime-agent integration guide.

What the integration is. A PrimeAgentFleet is a thin Python layer around the same engraphis-mcp Smart gateway every other host uses. At runtime the fleet holds one shared EngraphisMcpClient, which owns one engraphis-mcp subprocess over JSON-RPC stdio. Each of the eight named sub-agents gets its own Engraphis session (started lazily on first tool use) and its own default repo scope, so per-role memory is isolated while the local gateway stays single-process. The eight sub-agent names (researcher, planner, coder, reviewer, tester, documenter, monitor, integrator) are the fixed default; pass agent_names=[...] to PrimeAgentFleet(...) for a custom set. Concurrent tool calls serialize at the JSON-RPC frame layer through an asyncio.Lock, so framework-level parallelism (eight sub-agents reasoning at once) is preserved while the underlying MCP transport remains one ordered stream. The only integration surface is EngraphisPrimeAgent.register() in integrations/prime_agent/src/engraphis_prime_agent/agent.py -- that is the single adapter point to override if prime-agent's tool-registration API differs from the assumed target.register_tool(name, fn, schema=...) contract.

The design -- eight named sub-agents, one shared stdio subprocess, per-agent session bootstrap, and ENGRAPHIS_*-only environment forwarding to the gateway -- is recorded in ~/.commandcode/plans/prime-agent-integration.md on the host where the integration was developed. When that host plan is not available (other contributor machines, CI), the same design is summarized in the PR description that introduced the integration and in the prime-agent integration guide ("Architecture" and "Concurrency model" sections).

Quickstart: repository graph

bashCopy code
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:

bashCopy code
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.

Quickstart: Python library

pythonCopy code
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. The package root also intentionally exposes the low-level engine facade (MemoryEngine, create_memory_engine) for advanced composition, while MemoryService remains the high-level service API.

New writes support session, repo, and workspace visibility. scope="user" is reserved and rejected until records carry an immutable owner identity; it must not be treated as private per-person memory. Historical user-scope rows remain workspace-bound for compatibility.

After an upgrade, stats() reports prompt-eligibility counts and active embedding-space coverage. Zero-result recall identifies a review-gated scope instead of silently looking empty, and engraphis-cli review list|approve provides a dry-run-first local bulk workflow. Embedding model changes trigger a guarded rebuild; vector recall stays disabled until every stored vector matches the new fingerprint. See recall recovery.

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

pythonCopy code
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.

Govern memories without losing history

Engraphis separates automatic write resolution from explicit human governance:

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

pythonCopy code
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-index 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.

Free forever vs. hosted plans

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.

MCP tools

Engraphis exposes a zero-configuration Smart MCP gateway plus a 35-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.

Graphs and privacy-safe receipts

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

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.

The public package ships the same sync client as a console script and CLI verb: engraphis-sync (installed entry point), engraphis sync ..., and python -m scripts.sync --status for local-only state without network activity. See Cloud Sync for flags, encryption, merge behavior, and the local folder exchange.

Security and trust boundaries

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.

Encryption at rest

Set ENGRAPHIS_DB_KEY (or ENGRAPHIS_DB_KEY_FILE) and install the extra:

bashCopy code
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:

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

When using ENGRAPHIS_DB_KEY_FILE, provision a regular secret file readable only by the service identity. Engraphis rejects links, reparse points, hard links, malformed text, and oversized key files rather than following an unexpected filesystem object.

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 files and folders

The dependency-free universal core scans Markdown, plain text, RST, HTML, JSON/JSONL, CSV/TSV, configuration/XML text, source code, RTF, DOCX/ODT, XLSX/ODS, PPTX/ODP, and EPUB into the normal v2 memory path. Installed local resource adapters add PDF text, image OCR, and explicitly local-model audio/video transcription. Start with a zero-write preview, then confirm the same source collection explicitly:

bashCopy code
engraphis import documents /path/to/collection --workspace acme --dry-run
engraphis import documents /path/to/collection --workspace acme --repo product --yes

The CLI never downloads an embedding model during import. Use a model that is already cached, set ENGRAPHIS_EMBED_MODEL=local:/absolute/model/path, or explicitly set ENGRAPHIS_EMBED_MODEL to an empty value to use dependency-free deterministic hashing in lexical degraded mode.

The dashboard’s Import local documents flow offers the same preview, target scope, source label, conflict policy, cancellation, and resumable progress. Re-imports are idempotent, preserve temporal history, and report source removals without hard-deleting memories. Obsidian remains the rich Markdown adapter for frontmatter, aliases, wikilinks, and attachment references:

bashCopy code
engraphis import obsidian /path/to/vault --workspace acme --dry-run

See the document import guide for supported formats, source safety, resume and conflict behavior, optional adapters, and limitations; see the Obsidian adapter guide for Markdown-specific behavior.

Consolidation and automation

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.

Configuration

Values come from the process environment. Engraphis also loads the owner-private ~/.engraphis/config.env; ENGRAPHIS_ENV_FILE can select another absolute owner-private regular file. It never searches the working directory for .env, and explicit process variables win.