engraphis AGENTS.md

AGENTS.md — Engraphis

Engraphis is a local-first, open AI memory engine for agents — Ebbinghaus decay, interaction-aware reinforcement, bi-temporal facts, hybrid recall, and a native workspace → repo → session → memory hierarchy. Python 3.9+ for the core (Python 3.10+ for the server/MCP stack), FastAPI, SQLite, and local embeddings; the external LLM is optional and pluggable.

This is the canonical operating manual for any AI agent working in this repo. CLAUDE.md imports it. Read §0 before editing anything.

---

0. Read this first — two architectures live in one package

There are two parallel codebases under engraphis/. Confusing them is the single most common mistake here.

	v2 — current architecture (build here)	v1 — legacy reference server
Status	Primary scoped, bi-temporal, interface-driven implementation.	Compatibility/reference implementation with flat namespaces.
Model	Scoped + bi-temporal + typed; interface-driven.	Single flat namespace string per memory.
Code	engraphis/core/, engraphis/backends/, eval/, tests/, scripts/migrate_to_v2.py	engraphis/app.py, config.py, models.py, routes/, stores/, engines/, llm/, static/
Data	new v2 schema (SCHEMA_VERSION = 16)	engraphis_v1.db
Entry	engraphis.MemoryEngine.create() / engraphis.create_memory_engine() → engraphis/factory.py → core/engine.py	Internal reference only; never a public launcher

Rule: build new capability on v2 (core/ + backends/) behind the interfaces. Only touch the v1 server for compatibility fixes or to keep the reference running. When a task is ambiguous, decide which side it belongs to before editing.

---

1. Commands

# ── Install ──────────────────────────────────────────────────────────────────
pip install numpy pytest            # v2 core + tests, fully offline (Python 3.9 floor job)
pip install -e ".[test]"            # full offline CI test/lint/typecheck dependencies
pip install -e ".[all,dev]"         # complete local stack: dashboard, MCP, embeddings, dev tools
# Config: process environment or owner-private ~/.engraphis/config.env; never a searched CWD .env

# ── Primary offline gate (no API key — KEEP THIS GREEN; mirrors CI's full-stack job) ──
ruff check .                                                        # pinned lint rules
python scripts/check_commercial_manifest.py                         # source/service boundary
python scripts/externalize_dashboard_assets.py                      # strict-CSP asset drift
python -m pytest tests/ -q                                          # full offline unit suite
python -m eval.harness --dataset eval/datasets/sample.jsonl --k 5   # retrieval eval gate
python -m eval.harness --dataset eval/datasets/codemem.jsonl --k 5  # coding/conflict gate
python -m eval.ablation                                             # vector-only vs hybrid
python -m eval.reinforcement                                        # bounded retention trajectory
python -m eval.adversarial_memory_security                          # prompt/graph boundary
python -m eval.grounded                                             # grounded-abstain decision gate
python -m eval.code_arm                                             # coding-agent arm gate
pyright                                                             # core + backends typecheck

# ── External benchmarks (real numbers need torch + the dataset; see eval/external.py) ──
python -m eval.external --dataset locomo10.json --format locomo --k 10        # LoCoMo
python -m eval.external --dataset longmemeval_s.json --format longmemeval     # LongMemEval
python -m eval.external --dataset locomo10.json --format locomo --offline --limit 2  # plumbing check

# ── Unified dashboard + memory inspector ──
python -m scripts.start_dashboard    # http://127.0.0.1:8700
# Use this unified launcher; there is no separate Inspector service.

# ── Onboarding (writes owner-private ~/.engraphis/config.env; doctor verifies install) ──
engraphis-init                   # or: python -m scripts.init
engraphis-init --check

# ── Customer-side hosted session ───────────────────────────────────────────
ENGRAPHIS_CLOUD_CONTROL_URL=https://api.engraphis.com
ENGRAPHIS_CLOUD_REFRESH_CREDENTIAL=...  # secret; prefer the owner-only session file
ENGRAPHIS_CLOUD_TOKEN_SUBJECT=member    # device or member, fixed at bootstrap
# Authorization, billing, relay, compute, and worker implementations are private services.

# ── Sleep-time consolidation (schedulable local job; also an MCP tool) ────────
python -m scripts.consolidate --db engraphis.db --workspace acme --dry-run

# ── Sync (local shared-folder transport or hosted Cloud Sync — see docs/SYNC.md) ──
python -m scripts.sync --db engraphis.db --workspace acme --remote ~/Dropbox/engraphis --dry-run
python -m scripts.sync --db engraphis.db --workspace acme --relay https://relay.engraphis.com  # or bare --relay + ENGRAPHIS_RELAY_URL

# ── Compatibility server alias (v2, headless; needs the full install) ────────
python -m scripts.start_server      # same v2 app as engraphis-dashboard, without opening a browser
python -m scripts.cli recall "what do we know about X" -n vault    # CLI: ingest/recall/chat/thoughts/list

# ── v2 data migration (v1 flat namespaces → v2 scoped/bi-temporal) ───────────
python -m scripts.migrate_to_v2 --old engraphis_v1.db --new engraphis_v2.db --dry-run
python -m scripts.migrate_to_v2 --old engraphis_v1.db --new engraphis_v2.db