engraphis 0.9.6

Local-first AI memory engine for agents — Ebbinghaus decay, interaction-aware recall, bi-temporal facts, hybrid retrieval, and an MCP server. You bring the LLM.

Engraphis

https://engraphis.com/

https://discord.com/invite/Wfr2ejBmY

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

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

---

Open-Source users: Remember to Update regularly! Improvements and fixes twice a day. Invite your friends!

Beta: the Team layer (multi-user dashboard, seats, roles, audit log, team invite emails, cloud sync relay) is early-access beta — expect rough edges and breaking changes before it stabilizes. The single-user engine, dashboard, and MCP server are stable.

The WebUI — one command, local-first

pip install "engraphis[server]"
engraphis-dashboard

Opens http://127.0.0.1:8700 in your browser. No cloud, no signup, no API key for memory. Everything lives in a single SQLite file on your machine.

You'll see the full product — a dark-themed (with multiple theme options in left sidebar), sidebar-navigated dashboard with 14 tabs:

Tab	What you see
Overview	Live memory counts, memory-type mix, and a health summary at a glance
Analytics (Pro)	Growth, retention distribution, decay forecast, resolver mix, and top entities — plus a one-click shareable HTML report and a cross-workspace portfolio view
Recall	Hybrid search across the memory bank — each result shows its score breakdown (retention, semantic, lexical, graph, importance, recency)
Memories	Browse and curate every memory by workspace — click into a full reader with type and retention pills, drag-to-reorder, inline title/type edits
Proactive	"What should I know right now" — importance × recency × retention, plus the last session handoff
Why	The current answer to a question, and the facts it superseded
Timeline	Bi-temporal history of a topic — what was believed, and when
Audit	Full governance ledger — who did what, when, and why
Knowledge Graph	Interactive force-directed graph of entities and their relationships — click any node to see every linked memory
Consolidate	Run a consolidation sweep on demand — see what got distilled and what got pruned
Automation (Pro)	Scheduled consolidation + retention policies on autopilot — plus auto-dreaming: a background consolidation + cross-cluster inference loop that fires when the store has accumulated enough new memories and gone idle. Configurable from the dashboard (cadence, dream trigger, idle threshold, inference toggle) or the GET/POST /api/automation API, and via scripts/auto_maintain for cron / Task Scheduler
Workspaces	Create, rename, describe, copy, merge, and delete workspaces; import files & folders; drag-and-drop upload
Team (beta)	Multi-user access with PBKDF2 logins, password reset, admin / member / viewer roles, seat management, and team audit log (Team) — early-access beta
Settings	License activation (Pro/Team), cloud sync, LLM provider setup/test, Agent Connect token management, appearance, and engine/store info

The dashboard is powered by the v2 engine — the same MemoryService that backs the MCP server and the Python library. What you see in the UI is what your agents get.

Start it on every platform

Platform	How
Windows	Double-click Engraphis Dashboard on your Desktop or Start Menu (install: engraphis-dashboard --install-shortcuts)
macOS	Double-click Engraphis Dashboard.app on your Desktop (install: same command)
Linux	Desktop entry in Applications → Development (GNOME/KDE/etc.)
Docker	docker compose up — see docker-compose.yml for the one-command deployment
Any	engraphis-dashboard in a terminal

Accessibility-first inspection, built in

The dashboard has the focused memory-inspection view built in — no separate app or port:

• Open any memory to see its supersession chain with word-level diffs — exactly when a fact changed and why
• Offline knowledge graph (vendored renderer — no CDN, works air-gapped)
• Score breakdowns on every recall, Why/Timeline/link browsing, proactive recall, consolidation, audit trail
• Keyboard-navigable, ARIA-annotated, light/dark mode

The standalone Inspector (:8710) was retired 2026-07-10 and folded into the one dashboard on :8700.

---

What's under the UI

Your agents forget everything between sessions. Engraphis fixes that — on your machine. Every new session, your coding agent starts from zero: re-asking which package manager you use, re-learning the codebase, forgetting why you chose PASETO over JWT. Engraphis gives agents durable, scoped, explainable memory.

Under the hood: Ebbinghaus forgetting-curve decay, interaction-aware reinforcement, bi-temporal facts, and hybrid (vector + lexical + graph) recall. The engine is 100% local: SQLite + local embeddings. You bring an LLM only for optional chat, synthesis, structured extraction, or structured consolidation.

• Local-first & private — runs offline; the core depends only on numpy.
• MCP-native — 20 tools for Claude Code, Cursor, Cline, Zed, Windsurf.
• Self-maintaining facts — writes are deterministically conflict-resolved (no LLM required).
• Principled recall — six-term score over retention, semantic, lexical, graph, importance, recency.
• Bi-temporal truth — contradictions invalidate instead of overwriting (engraphis_why / engraphis_timeline).
• Grounded, not guessed — cited answers or explicit abstain; provenance on every memory.
• Task-ready context — bounded proactive packets combine task/agent state, cited memories, suggested follow-ups, and the last-session handoff; optional LLM prose is accepted only when its citations validate.
• Composable intelligence — opt-in deterministic conflict triage (duplicate / refinement / contradiction / obsolete) and UserModel recall reranking helpers; neither changes default recall unless called.
• Code-aware — AST-powered symbol graph: engraphis_index_repo → engraphis_search_code.
• Sleep-time consolidation — scheduled job distills recurring episodes, reports its compaction.
• Scoped — workspace → repo → session hierarchy.
• Encryption at rest — optional SQLCipher (AES-256) whole-database encryption via ENGRAPHIS_DB_KEY. No plaintext fallback when a key is set.
• Cloud sync — cross-device and cross-team memory sync with deterministic CRDT merge (folder transport for self-hosting, managed relay for zero-setup). One-click "Sync now" or automatic cadence in the dashboard.
• Import & ingest — drag-and-drop file upload, server-side folder import, and LLM-powered fact extraction from raw text.

---

Why it wins

Axis	mem0	Zep	Engraphis
Product WebUI (local, no cloud)	✗	✗	✓ (dashboard with built-in inspector)
Open & self-hostable engine	✓	partial	✓ fully open, local-first
Forgetting/decay	partial	✗	✓
Bi-temporal graph	partial	✓	✓
Native multi-repo model	✗	✗	✓ (unique)
Code-aware (AST/symbol graph)	✗	✗	✓ (unique)
Cloud sync (CRDT merge)	✗	✗	✓ (deterministic, no conflict copies)
Encryption at rest	✗	✗	✓ (SQLCipher)
MCP-native for coding agents	✓	✗	✓

---

Host on Railway (team, no install for members)

The dashboard ships as a Docker image that defaults to the v2 team dashboard (multi-user logins, roles, seats, cloud-license revocation). Deploy one instance for your team; members sign in at your URL and connect their agents over HTTP/MCP — they never install Engraphis locally. See docs/HOSTING_RAILWAY.md for the 5-minute guide (volume, custom domain, bootstrap the Team entitlement, create the first admin, invite members, and connect agents).

The button provisions a service from this repo's Dockerfile. After it builds, you add a persistent /data volume (so activated keys + memories survive redeploys) and set ENGRAPHIS_FORWARDED_ALLOW_IPS=* — both one-click steps in the Railway dashboard; full walk-through in the hosting guide.

Install

pip install "engraphis[all]"        # dashboard + MCP server + code graph + encryption + everything
pip install "engraphis[server]"     # dashboard + REST API
pip install "engraphis[mcp]"        # MCP server only
pip install "engraphis[encryption]" # SQLCipher encryption-at-rest extra
pip install engraphis               # core library — numpy only, fully offline

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 — python3 -m venv venv && source venv/bin/activate && pip install "engraphis[server]" — or 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 a deterministic offline embedder so it always runs.

---

Quickstart — dashboard (the headline)

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

Docker

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

The default entrypoint is engraphis-dashboard --no-open. Set ENGRAPHIS_API_TOKEN to require authentication, ENGRAPHIS_DB_KEY to encrypt the database at rest, and ENGRAPHIS_LICENSE_KEY to unlock Pro/Team features. See docker-compose.yml for all options.

---

Quickstart — MCP server (for coding agents)

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

Your agent now has 20 tools — remember, recall (grounded + proactive), proactive context, grounded answer alias, why, timeline, forget, pin, correct, ingest, consolidate, index_repo, search_code, link, record_event, start/end_session, stats. See the MCP tools table below.

---

Quickstart — Python library

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.

---

Free forever vs. Pro

The core engine, single-user dashboard, standalone MCP server, and governance tools are free and Apache-2.0, permanently. Paid Pro/Team keys are server-authoritative: the vendor signature is checked locally, then the key must hold a current machine-bound lease from the configured/vendor relay. Revoked, expired, or seat-exceeded keys fail closed; an unexpired lease provides bounded grace for transient network failures. Pro is $10/mo ($100/yr), Team is $20/seat/mo ($200/seat/yr), and the dashboard offers a 3-day server-issued Pro or Team trial after email confirmation — no card required.

Team is early-access beta. Multi-user logins, seats, roles, the team audit log, team invite emails, and the cloud-sync relay are all in active development — expect rough edges and breaking changes. Pro (single-user paid features) is stable. Free is stable.

	Free (available now)	Pro — $10/mo or $100/yr	Team — $20/seat/mo or $200/seat/yr
Dashboard WebUI (with built-in inspector)	✓	✓	✓
Memory engine + 20 MCP tools	✓	✓	✓
Version-chain diffs, offline knowledge graph	✓	✓	✓
Cloud sync (folder + managed relay)		✓	✓
Auto-sync (hands-off cadence)		✓	✓
Analytics: growth, retention, decay forecast + entities		✓	✓
Analytics HTML report (self-contained, shareable)		✓	✓
Automated maintenance: scheduled consolidation + retention policies + auto-dreaming		✓	✓
Signed compliance export (checksummed bi-temporal bundle)		✓	✓
Priority support		✓	✓
Multi-user dashboard: logins, roles, seat management (beta)			✓
Team audit log + CSV export (beta)			✓
Team invite emails (vendor relay, zero email setup) (beta)			✓

---

MCP tools

Category	Tool	What it does
Write	engraphis_remember	Store a fact; deterministically resolved (add/reinforce/supersede)
Write	engraphis_record_event	Append a lightweight episodic log entry
Write	engraphis_link	Explicitly connect two related memories
Write	engraphis_ingest	Apply the configured extractor (chunk, llm, or llm_structured); none stores one verbatim memory
Write	engraphis_consolidate	Run a sleep-time sweep; optionally build entity profiles or schema-validated LLM facts
Read	engraphis_recall	Hybrid vector + lexical + graph recall
Read	engraphis_recall_grounded	Cited answer from retrieved memories — or abstain
Read	engraphis_answer	Backward-compatible grounded-answer alias
Read	engraphis_recall_proactive	"What should I know right now" — no query needed
Read	engraphis_proactive_context	Task-aware context packet with cited memories and session handoff
Read	engraphis_why	Current answer + what it superseded
Read	engraphis_timeline	Full bi-temporal history, oldest first
Code	engraphis_index_repo	Parse a repo into the code symbol graph
Code	engraphis_search_code	Find symbols by name, with callers
Governance	engraphis_forget	Retire a memory — bi-temporal close, never deleted
Governance	engraphis_pin	Exempt from future automatic decay/pruning
Governance	engraphis_correct	Replace content without losing history
Session	engraphis_start_session / engraphis_end_session	Session lifecycle with cross-session handoff
Ops	engraphis_stats	Memory counts for health checks

---

Cloud sync

Cloud sync keeps your memory store consistent across all your machines — and, on the Team tier, across a group — without giving up local-first ownership. It ships two transports:

• Folder transport — any shared directory (Dropbox, iCloud, Syncthing, a git repo, a mounted drive). Zero infrastructure.
• Managed relay — HTTPS against the Engraphis relay, authenticated by your license key. One-click in the dashboard or python -m scripts.sync --relay.

Sync is a state-based CRDT: deterministic merge, no conflict copies, no data loss. Every field resolves by a commutative, idempotent rule so merge(A, B) == merge(B, A). See docs/SYNC.md for architecture, security model, and CLI usage.

---

Encryption at rest

Set ENGRAPHIS_DB_KEY (or ENGRAPHIS_DB_KEY_FILE) and install the extra:

pip install "engraphis[encryption]"

The entire database file is transparently encrypted with AES-256 via SQLCipher — full-text search, the graph, and every query keep working unchanged. When a key is set, Engraphis fails loud 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 files & folders

Drag-and-drop or server-side import, both member-gated and bounded:

• Dashboard upload — the Workspaces tab's "Import files & folders" section accepts files directly from the browser.
• Server-side folder import — MemoryService.import_folder() reads a directory on the machine running Engraphis, defaulting to one memory per file. With ENGRAPHIS_EXTRACTOR=chunk, each file becomes retrieval-sized chunk memories. Path-traversal guards still apply.
• MCP ingest — engraphis_ingest accepts raw text and applies the configured extractor (chunk, llm, or llm_structured); with none it stores one verbatim memory.
• Sub-file chunking — set ENGRAPHIS_EXTRACTOR=chunk to split long, multi-topic documents into retrieval-sized, structure-aware pieces (headings start new chunks; ~256-token target with sentence-level overlap) without an LLM. Each chunk becomes its own memory, so recall returns the relevant passage instead of a whole file — a big context-reduction win on long docs. Works across all three ingest paths (dashboard upload, import_folder, and engraphis_ingest). Measure the payoff with the bundled eval: python -m eval.chunking_eval --dataset eval/datasets/longdoc.jsonl --k 5 (whole-file vs. chunked, same recall pipeline, offline).
• Structured LLM extraction — ENGRAPHIS_EXTRACTOR=llm_structured validates typed facts, entities, relations, keywords, and confidence before storage. Its preserved entity/relation metadata feeds the knowledge graph automatically.

Files imported through the dashboard or import_folder() are marked untrusted by default; MCP ingest remains an authenticated agent write.

---

Consolidation and automated maintenance

Manual consolidation is free. The Pro Automation tab (and the GET/POST /api/automation plus POST /api/maintenance/run API) can keep the store clean without you clicking anything, using a maintenance policy with two modes that compose:

• Scheduled maintenance — a consolidation + retention sweep on a fixed cadence (cadence_hours). Recurring episodic memories are distilled into semantic digests, and memories fading below archive_below retention are archived bi-temporally (pinned memories are always protected).
• Auto-dreaming — a background consolidation + cross-cluster inference loop (no cron needed — it runs inside the dashboard process) that fires when both hold: the store has accumulated ≥ dream_min_new new episodic memories since the last sweep, and the store has been idle for dream_idle_minutes. Dreaming emits low-salience dream_inference memories (cross-cluster/entity profiles, marked untrusted and linked back to their sources) so inferred knowledge is auditable and never silently promoted.

Knobs (dashboard Automation tab ↔ /api/automation API): enabled, cadence_hours, consolidate, min_cluster, archive_below, dream, dream_min_new, dream_idle_minutes, infer. Headless / no-dashboard-open: python -m scripts.auto_maintain --apply (via Task Scheduler or cron).

Manual consolidation can also use schema-validated LLM output through MemoryService.consolidate, POST /api/consolidate, engraphis_consolidate, or python -m scripts.consolidate --structured. Source memories remain live by default; supersede_sources / --supersede-sources closes them only after validated replacement facts are written.

---

Configuration

All via environment (or .env):

Env Var	Default	Description
ENGRAPHIS_DB_PATH	<project/package root>/engraphis.db	SQLite database file
ENGRAPHIS_HOST	127.0.0.1	Server bind address
ENGRAPHIS_PORT	8700	Dashboard port
ENGRAPHIS_API_TOKEN	—	If set, REST API requires Authorization: Bearer <token>
ENGRAPHIS_DB_KEY	—	Encrypt the database at rest (SQLCipher). Or use ENGRAPHIS_DB_KEY_FILE
ENGRAPHIS_EMBED_MODEL	sentence-transformers/all-MiniLM-L6-v2	sentence-transformers model
ENGRAPHIS_EXTRACTOR	none	none = verbatim; chunk = offline structure-aware chunks; llm = free-form LLM facts; llm_structured = schema-validated facts + graph metadata
ENGRAPHIS_GRAPH_EXTRACTOR	regex	regex = offline heuristic NER; none = disable heuristic text extraction (validated llm_structured metadata still feeds the graph)
ENGRAPHIS_LLM_PROVIDER	openai	openai | anthropic | google | openrouter | custom
ENGRAPHIS_LLM_MODEL	gpt-4o-mini	Model name (provider-specific)
ENGRAPHIS_LLM_API_KEY	—	API key for chat/synthesis, llm / llm_structured extraction, and structured consolidation
ENGRAPHIS_LLM_BASE_URL	—	Base URL for openrouter / custom OpenAI-compatible endpoints
ENGRAPHIS_LICENSE_KEY	—	Pro/Team key (or ~/.engraphis/license.key)
ENGRAPHIS_TEAM_MODE	1	Mount Team features by default; the auth wall activates for a live Team license or an existing team. Set 0 to disable
ENGRAPHIS_LOOP_INTERVAL	60	Background consolidation loop interval in seconds (0 = disabled)
ENGRAPHIS_DECAY_HALFLIFE_DAYS	7	Ebbinghaus decay half-life (higher = memories persist longer)
ENGRAPHIS_FORWARDED_ALLOW_IPS	127.0.0.1	Trusted reverse-proxy IPs for TLS termination (* = trust all)
ENGRAPHIS_RELAY_URL	https://team.engraphis.com	Managed sync, license, trial, and invite relay (Pro/Team); the retired Railway URL is migrated automatically
ENGRAPHIS_AUTOSYNC_LOOP	1	Kill switch for the in-process auto-sync loop (0 = off)

See .env.example for the full list including commercial/vendor, email delivery, and cloud-license enforcement options.

---

Project structure

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        # MCP server — 20 tools
│   ├── dashboard_app.py     # dashboard WebUI (FastAPI)
│   ├── autosync.py          # background auto-sync loop (Pro/Team)
│   ├── licensing.py         # license verification (offline + cloud)
│   ├── analytics.py         # Pro analytics engine
│   ├── automation.py        # scheduled maintenance policies (Pro)
│   ├── billing.py           # Polar webhook fulfillment
│   ├── config.py / app.py   # env settings / REST server
│   └── static/              # dashboard frontend
├── eval/                    # offline retrieval eval harness + datasets
├── tests/                   # pytest suite (300+ tests, offline numpy-only core)
├── scripts/                 # start_dashboard, inspector, cli, init, consolidate, sync
├── docs/                    # SYNC.md, KILO_CODE_INTEGRATION.md
├── Dockerfile / docker-compose.yml
└── pyproject.toml

---

Development

The offline quality gate (no network, no API key):

pip install numpy pytest ruff
python -m pytest tests/ -q
python -m eval.harness --dataset eval/datasets/sample.jsonl --k 5
python -m eval.harness --dataset eval/datasets/codemem.jsonl --k 5
python -m eval.ablation
ruff check .

Numbers, not assertions: the offline harness is a correctness floor (deterministic embedder). LoCoMo / LongMemEval competitive numbers run separately with a real embedder — see BENCHMARKS.md.

---

License

Apache-2.0 — see LICENSE and NOTICE. "Engraphis" is a trademark of the Engraphis project; the license does not grant trademark rights.