feat: 1.4.5 release — governed recall, schema v8, Smart gateway

.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
       "name": "engraphis-memory",
       "source": "./",
       "description": "Discipline for giving agents durable, scoped, explainable memory across sessions and repos with the Engraphis MCP tools.",
-      "version": "1.4.0"
+      "version": "1.4.5"
     }
   ]
 }

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "engraphis-memory",
-  "version": "1.4.0",
+  "version": "1.4.5",
   "description": "Give agents durable, scoped, explainable memory across sessions and repos via the Engraphis MCP tools. Use when you learn something worth keeping, need prior context before acting, or ask why/how a fact changed. Covers remember/recall, why/timeline, forget/pin/correct, sessions, and code search.",
   "author": {
     "name": "The Engraphis Authors",

.claude-plugin/skill-assets.sha256

@@ -1,6 +1,6 @@
-b3122186525b688060558721dadf8ca4a20e192097556adb1daecca0649a4e28  .claude-plugin/marketplace.json
-5a870fabc9814e177a570a8878371d1c4c50a5b245076c2cfbb7ca659e41ebf6  .claude-plugin/plugin.json
-911c70ead2c5aa3de24a6c645a9e921382a149aba52b0a9582ecd5b560e5b8a8  skills/engraphis-memory/SKILL.md
+e7e4ecd111d9b04c290ddd60e0fadb90e3afd8c67e39dcb8fbce0b50b5e3ce42  .claude-plugin/marketplace.json
+65bff1596f3db2bc75b74c6970d87e806d46ef1cb3e612cd2002f19c3a8f6acb  .claude-plugin/plugin.json
+56be8d078a2a8fc6e6cd1c2be5716605d8621dab953caa8cfcd20e2dce474305  skills/engraphis-memory/SKILL.md
 45dd73ca6afdd9e12ecd38c48e4a612b7646c25a07a75a80ca0e68d0e0b85f0e  skills/engraphis-memory/references/CONVENTIONS.md
 529fff3bdbe73f83209087fd10055fad77c5e5224ad8a9e6b0254052aa50e109  skills/engraphis-memory/references/SCOPING.md
 eecd861f0f8cc2a9def07a53387ca66d8cb68d8b62d9b048dcd1b0b250fa3fee  skills/engraphis-memory/references/TOOLS.md

.dockerignore

@@ -7,10 +7,59 @@ __pycache__
 *.db
 *.db-wal
 *.db-shm
+*.db-journal
+*.bak
 .env
 .venv
 venv
 docs/_build
 *.egg-info
 build
 dist
+# Test and local tooling output.
+.coverage
+.coverage.*
+htmlcov
+.tox
+.nox
+.hypothesis
+.audit-venv
+models_cache
+.secrets
+internal
+.commandcode
+
+# Machine-local runtime state and credentials.
+.engraphis_processed_webhooks
+undelivered_license_keys.tsv
+automation.json
+autosync.json
+.engraphis_update_check.json
+cookies.txt
+
+# Private research and local demo material.
+/COMMERCIAL_AUDIT.md
+/COMPETITIVE_ANALYSIS.md
+/docs/COMMERCIAL_AUDIT.md
+/docs/COMPETITIVE_ANALYSIS.md
+/demo/generated/
+/demo/output/
+/demo/assets/
+/demo/*_killer.html
+/demo/*_social_demo.html
+
+# Local QA/eval/automation state — never part of the build context.
+node_modules
+integrations/pi/node_modules
+test-results
+playwright-report
+.playwright
+.private-eval
+.hosted-eval-results
+/.tmp-*/
+/.tmp_*/
+/.release-full-tmp/
+/_to_delete/
+*.log
+*.whl
+*.tar.gz

.env.example

@@ -21,9 +21,10 @@ ENGRAPHIS_SERVICE_MODE=customer
 # Behind Traefik, use its LAN hostname instead:
 # ENGRAPHIS_DASHBOARD_URL=http://engraphis.local
 
-# Update reminder. When on (default), the server checks for a newer Engraphis release
-# once a day and surfaces it in the dashboard banner, the startup log, and over MCP.
-# The check is fail-silent and cached; set to 0 to disable all update network activity.
+# Update reminder. It is OFF by default, so a local installation makes no update-related
+# network request. Set this to 1 to check for a newer Engraphis release once a day and
+# surface it in the dashboard banner, startup log, and over MCP. The check is cached
+# and fail-silent.
 # ENGRAPHIS_UPDATE_CHECK=1
 # Override the release source. Default: the GitHub releases/latest API for the project
 # repo. Accepts any HTTPS endpoint returning a GitHub-release, PyPI, or
@@ -32,6 +33,11 @@ ENGRAPHIS_SERVICE_MODE=customer
 # Point the default GitHub source at a different owner/repo (ignored when
 # ENGRAPHIS_UPDATE_URL is set). Default: Coding-Dev-Tools/engraphis.
 # ENGRAPHIS_UPDATE_REPO=Coding-Dev-Tools/engraphis
+# Which extras the self-updater installs on top of the base package. The installer
+# cannot see which extras the current install selected, so it defaults to the safe
+# superset `engraphis[all]`; set a comma-separated list (e.g. `server,mcp`) to pin
+# a smaller surface, or `none` for the base package only.
+# ENGRAPHIS_UPDATE_EXTRAS=
 
 # Optional local API bearer. If set, supported protected routes accept
 # Authorization: Bearer <token>. Use a strong, independently revocable value and do not
@@ -70,10 +76,16 @@ ENGRAPHIS_API_TOKEN=
 ENGRAPHIS_EMBED_MODEL=sentence-transformers/all-MiniLM-L6-v2
 # Embedding dimension is auto-detected from the model. Override only if needed.
 # ENGRAPHIS_EMBED_DIM=384
+# Vector index backend for the v2 engine: "numpy" (default, deterministic reference
+# index), "sqlite-vec" (require the accelerated ANN backend; needs the sqlite-vec
+# package), or "auto" (use sqlite-vec when available, fall back to NumPy).
+# ENGRAPHIS_VECTOR_BACKEND=numpy
 
 # ── LLM (external, you choose the provider) ─────────────────────────────────
 # Provider: openai | anthropic | google | openrouter | custom
 # Copy-ready provider setups and endpoint requirements: docs/LLM_PROVIDERS.md
+# Codex subscription users: connect Codex to this installation over MCP; the subscription
+# path does not use ENGRAPHIS_LLM_PROVIDER or an Engraphis LLM API key.
 # ── v2 write-path fact extraction (optional) ─────────────────────────────────
 # "none" (default): store text as given. "chunk": deterministic offline chunks.
 # "llm": free-form fact extraction. "llm_structured": schema-validated typed facts,
@@ -97,6 +109,9 @@ ENGRAPHIS_GRAPH_EXTRACTOR=regex
 # "llm" sends a bounded excerpt to the configured provider for an advisory
 # ephemeral/normal/critical signal. Writes are never discarded.
 ENGRAPHIS_RETENTION_SUPERVISOR=none
+# A remote retention supervisor is advisory: without this opt-in, its "critical"
+# recommendations keep normal retention strength. Set 1 to honor critical signals.
+# ENGRAPHIS_ALLOW_AUTOMATIC_CRITICAL_RETENTION=0
 
 # Optional local resource adapters:
 # ENGRAPHIS_WHISPER_MODEL=/absolute/path/to/local-whisper-model
@@ -112,6 +127,19 @@ ENGRAPHIS_RETENTION_SUPERVISOR=none
 # ENGRAPHIS_GRAPH_HOST=127.0.0.1
 # ENGRAPHIS_GRAPH_PORT=8720
 
+# Standalone MCP-over-HTTP server (`engraphis-mcp-http`). Loopback-only by default;
+# any non-loopback bind (via these or ENGRAPHIS_HOST) requires ENGRAPHIS_API_TOKEN.
+# ENGRAPHIS_HTTP_HOST=127.0.0.1
+# ENGRAPHIS_HTTP_PORT=8080
+# ENGRAPHIS_HTTP_TRANSPORT=streamable-http
+
+# When running under Docker (auto-detected via /.dockerenv), the self-updater skips
+# in-place pip upgrades and prints a manual reinstall hint instead.
+# ENGRAPHIS_DOCKER=0
+
+# Docker Compose host port mapping override for the dashboard (default 8700).
+# ENGRAPHIS_COMPOSE_PORT=8700
+
 # ── Reverse proxy (TLS termination) ─────────────────────────────────────────
 # When behind a proxy that terminates TLS (Railway/Fly/nginx), trust its
 # X-Forwarded-Proto/-For headers so request.url.scheme is https and the session
@@ -135,6 +163,9 @@ ENGRAPHIS_RETENTION_SUPERVISOR=none
 # ENGRAPHIS_CSP=""                                             # send no CSP at all
 # ENGRAPHIS_HSTS="max-age=31536000; includeSubDomains"
 
+# Codex subscription users can use the local MCP connection documented in README.md and
+# docs/AGENT_CONNECT.md; leave the optional external LLM settings below disabled unless
+# Engraphis itself must call a separate provider.
 ENGRAPHIS_LLM_PROVIDER=openai
 # Model name (provider-specific):
 #   openai:      gpt-4o-mini, gpt-4o, gpt-4.1-mini, o4-mini ...
@@ -143,17 +174,12 @@ ENGRAPHIS_LLM_PROVIDER=openai
 #   openrouter:  anthropic/claude-3.5-sonnet, openai/gpt-4o-mini ...
 #   custom:      any model name your OpenAI-compatible endpoint accepts
 ENGRAPHIS_LLM_MODEL=gpt-4o-mini
-# API key for chat/synthesis, llm/llm_structured extraction, and structured consolidation:
-ENGRAPHIS_LLM_API_KEY=sk-your-key-here
+# API key for chat/synthesis, llm/llm_structured extraction, and structured consolidation.
+# Leave unset until you explicitly choose a provider and enable an LLM-backed feature.
+# ENGRAPHIS_LLM_API_KEY=<your-api-key>
 # For openrouter / custom: the base URL of the OpenAI-compatible endpoint.
 #   openrouter: https://openrouter.ai/api/v1
 #   custom:     https://your-endpoint/v1
-#   ollama:     http://localhost:11434/v1
-# Ollama example (replace the model with one you have pulled):
-#   ENGRAPHIS_LLM_PROVIDER=custom
-#   ENGRAPHIS_LLM_MODEL=qwen2.5-coder:latest
-#   ENGRAPHIS_LLM_API_KEY=ollama  # must be non-empty; default local Ollama ignores it
-#   ENGRAPHIS_LLM_BASE_URL=http://localhost:11434/v1
 # ENGRAPHIS_LLM_BASE_URL=https://openrouter.ai/api/v1
 # Optional: extra headers (JSON string) for custom providers.
 # ENGRAPHIS_LLM_EXTRA_HEADERS={"HTTP-Referer":"https://myapp.com","X-Title":"engraphis"}
@@ -277,6 +303,12 @@ ENGRAPHIS_LLM_API_KEY=sk-your-key-here
 # ENGRAPHIS_CHUNK_TOKENIZER_REVISION=<immutable model commit>
 # ENGRAPHIS_LOOP_INTERVAL=60
 # ENGRAPHIS_LOOP_TOP_K=20
+# Automatic local consolidation inside the background loop. OFF by default (0): the
+# sweep is a workspace-wide cluster scan, so it should be an explicit operator choice.
+# N > 0 runs it at most once every N loop ticks (e.g. 30 with a 60s interval ≈ every
+# 30 minutes). The sweep is deterministic/offline (never passes an LLM), archives
+# decayed transients, and distills recurring episodic memories into semantic digests.
+# ENGRAPHIS_LOOP_CONSOLIDATE=0
 # ENGRAPHIS_RERANK_MODEL=cross-encoder/ms-marco-MiniLM-L-6-v2
 
 # Workspace allow-list: comma-separated names. Empty = all allowed.
@@ -286,6 +318,11 @@ ENGRAPHIS_LLM_API_KEY=sk-your-key-here
 # ENGRAPHIS_RELAY_URL=https://relay.example.com
 # ENGRAPHIS_SYNC_TOKEN=
 # ENGRAPHIS_SYNC_READ_ONLY=0
+# End-to-end encryption key for Cloud Sync bundles (relay transport). A single
+# immutable 32-byte URL-safe base64 value (43 chars, or 44 with one '=' pad) that
+# every authorized device shares; changing it makes previously stored ciphertext
+# unreadable. The folder transport does not encrypt at rest — see docs/SYNC.md.
+# ENGRAPHIS_SYNC_E2EE_KEY=
 
 # Hosted plan upgrade URLs: override the default upgrade landing pages.
 # ENGRAPHIS_UPGRADE_URL=

.github/workflows/ci.yml

@@ -21,6 +21,8 @@ jobs:
       - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
       - name: Install (core + server/mcp/code extras; no torch or SQLCipher)
         run: |
           python -m pip install --upgrade pip
@@ -54,6 +56,8 @@ jobs:
       - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
       - name: Install encryption integration gate
         run: |
           python -m pip install --upgrade pip
@@ -72,6 +76,8 @@ jobs:
       - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: "3.9"
+          cache: pip
+          cache-dependency-path: pyproject.toml
       - name: Install (numpy-only core — the minimum supported runtime)
         run: |
           python -m pip install --upgrade pip
@@ -83,6 +89,37 @@ jobs:
       - name: Ablation
         run: python -m eval.ablation
 
+  coverage:
+    name: coverage gate (Python 3.11)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.11"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[test]" pytest-cov
+      - name: Coverage run (all extras-gated tests, tracked modules)
+        run: python -m pytest -o addopts="" tests/ -q -rs --cov=engraphis --cov-report=term-missing --cov-fail-under=60
+
+  hygiene:
+    name: repo hygiene gate (no stray DBs/logs)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+      - name: Reject stray runtime artifacts at repo root
+        run: |
+          stray=$(find . -maxdepth 1 -type f \( -name '*.db' -o -name '*.db-wal' -o -name '*.db-shm' \
+            -o -name '*.bak' -o -name '*.log' \) -print)
+          if [ -n "$stray" ]; then
+            echo "Refusing to commit stray runtime artifacts:"; echo "$stray"; exit 1
+          fi
+          echo "repo root clean"
+
   pi-extension:
     name: Pi extension (${{ matrix.os }}, Python ${{ matrix.python-version }}, Node ${{ matrix.node-version }})
     runs-on: ${{ matrix.os }}

AGENTS.md

@@ -20,7 +20,7 @@ most common mistake here.
 | 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 = 7`) | `engraphis_v1.db` |
+| Data | new v2 schema (`SCHEMA_VERSION = 9`) | `engraphis_v1.db` |
 | Entry | `MemoryEngine.create()` → `core/engine.py` | Internal reference only; never a public launcher |
 
 **Rule:** build new capability on **v2** (`core/` + `backends/`) behind the interfaces.
@@ -35,7 +35,7 @@ task is ambiguous, decide which side it belongs to *before* editing.
 # ── Install ──────────────────────────────────────────────────────────────────
 pip install numpy pytest            # v2 core + tests, fully OFFLINE (this is what CI does)
 pip install -e ".[all,dev]"         # full stack: FastAPI server, ST embeddings, ruff
-cp .env.example .env                # only needed for the v1 server / LLM features
+cp .env.example .env                # optional; configure server, LLM, encryption, or hosted client settings
 
 # ── Quality gate (offline, no API key — KEEP THIS GREEN; mirrors .github/workflows/ci.yml) ──
 python -m pytest tests/ -q                                          # unit tests (offline)
@@ -182,7 +182,7 @@ These are pure, unit-tested functions — change them only with a corresponding
 
 ---
 
-## 5. Data model cheat-sheet (`core/interfaces.py`, `core/schema.py` — `SCHEMA_VERSION = 7`)
+## 5. Data model cheat-sheet (`core/interfaces.py`, `core/schema.py` — `SCHEMA_VERSION = 9`)
 
 - **Scope hierarchy:** `workspace → repo → session → memory`. Scopes: `session|repo|workspace|user`.
 - **Bi-temporal validity on every record:** world-time `valid_from/valid_to` +
@@ -194,8 +194,7 @@ These are pure, unit-tested functions — change them only with a corresponding
 - **Tables:** `workspaces`, `repos`, `sessions`, `memories`, `mem_vectors`, `embedding_state`,
   `mem_fts` (FTS5 + plain-table fallback), `entities`, `edges` (bi-temporal), `mem_links`,
   `memory_entities`, `symbols`, `code_edges`, `code_files`, `code_memory_links`,
-  `operation_receipts`,
-  `events`, `audit`, `schema_migrations`.
+  `operation_receipts`, `events`, `audit`, `memory_tombstones`, `schema_migrations`.
 - **Vectors are stored L2-normalized** so cosine similarity == dot product.
 
 ---
@@ -230,8 +229,6 @@ These are pure, unit-tested functions — change them only with a corresponding
 - **`docs/HOSTED_PLANS.md`** — concise pricing, plan contents, trial, and hosted-service boundary.
 - **`docs/MCP_TOOLS.md`** — standalone inventory of the public MCP surface; keep it synchronized
   with `engraphis/mcp_server.py`.
-- **`docs/OLLAMA.md`** — local Ollama configuration. Keep setup details here instead of
-  duplicating them in the README.
 - **`docs/SYNC.md`** — cloud sync (Pro): architecture, the convergent merge, CLI usage, and the
   untrusted-bundle security model.
 - **`AGENTS.md`** (this file) + **`CLAUDE.md`** — how to work in the repo.