Skip to content

README.md

Latest commit

 

History

History
449 lines (349 loc) · 23.7 KB

README.md

File metadata and controls

449 lines (349 loc) · 23.7 KB
Raw

Engraphis

Version License Buy Me a Coffee

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.


Engraphis Knowledge Graph tab — force-directed entity-relation network
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 /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).

Deploy on Railway

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 Store raw text; Engraphis extracts the discrete facts worth keeping
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, one memory per file, with path-traversal guards.
  • MCP ingest — engraphis_ingest accepts raw text and extracts discrete facts when ENGRAPHIS_EXTRACTOR=llm or llm_structured is configured; otherwise it stores verbatim.
  • 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 /automation plus POST /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 ↔ /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 ./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 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 relay URL (Pro/Team)
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.