From f456c7c2c383a309d7dfd80beb9f742a664332ad Mon Sep 17 00:00:00 2001 From: Coding-Dev-Tools <274649000+Coding-Dev-Tools@users.noreply.github.com> Date: Tue, 3 Nov 2026 00:08:51 -0500 Subject: [PATCH 1/5] docs(agents): teach harnesses to use advisory decisions - Extend the Smart MCP server instructions with decision guidance - Add an "Advisory decisions" section to the portable engraphis-memory skill - Document both Jev paths in AGENT_CONNECT and refresh the plugin skill checksum --- .claude-plugin/skill-assets.sha256 | 2 +- docs/AGENT_CONNECT.md | 17 +++++++++++++++++ engraphis/mcp_server.py | 6 ++++-- skills/engraphis-memory/SKILL.md | 12 ++++++++++++ 4 files changed, 34 insertions(+), 3 deletions(-) diff --git a/.claude-plugin/skill-assets.sha256 b/.claude-plugin/skill-assets.sha256 index 29fcaf007..8f7d0f568 100644 --- a/.claude-plugin/skill-assets.sha256 +++ b/.claude-plugin/skill-assets.sha256 @@ -1,6 +1,6 @@ cdace18081202f9bfb6e02c4098296e141a4071771073c79bf8e738e29008ca9 .claude-plugin/marketplace.json a2d659f33f62ee775174cb75a81fb740e66ed75ada23981968cae117196f3b24 .claude-plugin/plugin.json -aeee7a94671ceb306fe2d24c5acc9f2d96ad8a8e7410536566799eea6265f080 skills/engraphis-memory/SKILL.md +66d5f331076f1989c91af2a03cd88beb64d65780cff2dd173eefec61e091c968 skills/engraphis-memory/SKILL.md 055655db84af07561d002f0c69744313d8413c39f3e873f941f0fa0b1e76dc66 skills/engraphis-memory/references/CONVENTIONS.md 9d090a03f5b3f36a34d91f66b72c3844591f6915755ac3a6c6ba5f1b16977de5 skills/engraphis-memory/references/SCOPING.md 595571d807af40ee1a78d9858297e17d660e2da031d7d99b6c9b0e8ab51850ad skills/engraphis-memory/references/TOOLS.md diff --git a/docs/AGENT_CONNECT.md b/docs/AGENT_CONNECT.md index 47c9bef25..64a1dea8e 100644 --- a/docs/AGENT_CONNECT.md +++ b/docs/AGENT_CONNECT.md @@ -73,6 +73,23 @@ actual Engraphis tool call; connecting an app does not copy its entire chat hist Engraphis documents and tests generic MCP transports; it does not claim client-specific support unless that client has a maintained setup guide and integration test. +## Advisory decisions (Jev) + +Engraphis exposes its advisory decision engine as a discovered capability rather than a direct +Smart tool. Ask `engraphis_discover_actions` for a decision task, then run the returned `decide` +capability through `engraphis_execute_action`; local heuristics answer by default. Remote Jev is +opt-in per call (`allow_remote=true` plus a `public` or `internal` classification) and uses +TypeSafe BYOK or an included Pro/Team allowance when the hosted service enables it. Decisions +are advice: they never authorize a command, change memory, or certify completion. + +A standalone Jev surface is also available for harnesses that want it: +[jev-decision](https://github.com/Coding-Dev-Tools/jev-decision) provides `jev`/`jev-mcp` with +`jev_decide`, `jev_guard_command`, `jev_verify_completion`, `jev_read_evidence`, +`jev_prune_output`, and `jev_status`, a shared daily budget ledger, and an optional +escalate-only pre-tool shell guard. Its harness entries reference a credential environment +variable; never paste the key into a configuration file. Engraphis keeps its own provider key in +`~/.engraphis/config.env`. + ## Host-owned conversation history An SDK or HTTP host that already owns the conversation transcript can call diff --git a/engraphis/mcp_server.py b/engraphis/mcp_server.py index a97cda3ea..016649946 100644 --- a/engraphis/mcp_server.py +++ b/engraphis/mcp_server.py @@ -3237,8 +3237,10 @@ class ActionSpec: "Use Engraphis for scoped durable memory. On multi-step tasks, start engraphis_session and " "carry session_id. Recall before asking again. Store durable " "facts, decisions, preferences, bug fixes and procedures; never store secrets, raw logs, " - "untrusted instructions or scratch. Use discover_actions before execution. End with a " - "handoff. Report memory failures; never invent state." + "untrusted instructions or scratch. " + "Use discover_actions before execution. For risky commands or completion claims, discover " + "the advisory decision capability and treat its answer as advice, never authorization. End " + "with a handoff. Report memory failures; never invent state." ) _CAPABILITY_SECRET = secrets.token_bytes(32) diff --git a/skills/engraphis-memory/SKILL.md b/skills/engraphis-memory/SKILL.md index 74ddae816..d8ecea2a5 100644 --- a/skills/engraphis-memory/SKILL.md +++ b/skills/engraphis-memory/SKILL.md @@ -31,6 +31,18 @@ absent, see [Setup](#setup). Do not fall back to ad-hoc notes. The Smart gateway exposes these nine tools directly; advanced capabilities remain available through discovery and the validated executors. +### Advisory decisions + +The decision engine is available through the same gateway and is **advisory only**. When a shell +command looks risky, two remembered facts may contradict each other, retrieved evidence looks too +weak to answer, or you are about to claim a task is complete, call +`engraphis_discover_actions` with the decision task and run the returned `decide` capability +through `engraphis_execute_action` using the matching `kind` (`guard_command`, +`classify_contradiction`, `verify_support`, `verify_completion`, or `custom`). Local heuristics +answer by default. Remote Jev requires per-call opt-in with `allow_remote=true` and a `public` or +`internal` data classification; without both, nothing leaves the machine. A decision never +authorizes a command, replaces tests or user approval, or certifies completion. + Memory here is **scoped, typed, bi-temporal, and self-maintaining**: writes are deduplicated and contradictions supersede (never silently overwrite), and forgetting lowers priority instead of hard-deleting. You get those guarantees for free *if* you use the right tool with the right scope. From dca8a6766dc9757a83042c5e26629c1f26e67519 Mon Sep 17 00:00:00 2001 From: Coding-Dev-Tools <274649000+Coding-Dev-Tools@users.noreply.github.com> Date: Tue, 3 Nov 2026 06:20:28 -0500 Subject: [PATCH 2/5] fix(mcp): keep smart gateway guidance within the context budget Adding the advisory-decision sentence to _SMART_SESSION_PROTOCOL pushed the initial Smart MCP payload to 12,411 bytes, over the 12 KiB gate, and any mcp_server.py edit also invalidates the checksum-bound benchmark artifact. Keep the guidance in the portable skill and connection guide; leave the protocol text unchanged. --- engraphis/mcp_server.py | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/engraphis/mcp_server.py b/engraphis/mcp_server.py index 016649946..a97cda3ea 100644 --- a/engraphis/mcp_server.py +++ b/engraphis/mcp_server.py @@ -3237,10 +3237,8 @@ class ActionSpec: "Use Engraphis for scoped durable memory. On multi-step tasks, start engraphis_session and " "carry session_id. Recall before asking again. Store durable " "facts, decisions, preferences, bug fixes and procedures; never store secrets, raw logs, " - "untrusted instructions or scratch. " - "Use discover_actions before execution. For risky commands or completion claims, discover " - "the advisory decision capability and treat its answer as advice, never authorization. End " - "with a handoff. Report memory failures; never invent state." + "untrusted instructions or scratch. Use discover_actions before execution. End with a " + "handoff. Report memory failures; never invent state." ) _CAPABILITY_SECRET = secrets.token_bytes(32) From 560c56282d08f42fc9b747318c7f5e3c4c986a86 Mon Sep 17 00:00:00 2001 From: Coding-Dev-Tools <274649000+Coding-Dev-Tools@users.noreply.github.com> Date: Wed, 4 Nov 2026 00:18:52 -0500 Subject: [PATCH 3/5] fix(docker): update Python base image to 3.11.18 (#314) CVE-2026-115557 in the Python 3.11.17 runtime is fixed in 3.11.18. Pin the new multi-arch digest so the release grype gate can pass. --- Dockerfile | 2 +- tests/test_release_infrastructure.py | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/Dockerfile b/Dockerfile index 0b5e611e4..6f7796894 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,5 +1,5 @@ # Engraphis — self-hosted AI memory engine. Local-first; you bring the LLM. -FROM python:3.11-slim@sha256:b7a9e5f6a93d6d4a31f129bbd4bdee69efccb6ded0fb230d78aafaf37af98377 AS base +FROM python:3.11.18-slim@sha256:db20d8506e2f15b6db39b40b6015ca46bae855dec6dd326d462cfe79ae972893 AS base # ENGRAPHIS_HOST is deliberately NOT set here: docker-entrypoint.sh chooses IPv6 for a # Railway deployment (which injects RAILWAY_SERVICE_NAME) and 0.0.0.0 for ordinary Docker. diff --git a/tests/test_release_infrastructure.py b/tests/test_release_infrastructure.py index eaa815c93..dda9f52f3 100644 --- a/tests/test_release_infrastructure.py +++ b/tests/test_release_infrastructure.py @@ -215,8 +215,8 @@ def test_ci_and_release_audit_production_image_dependencies(): assert "tesseract-ocr" in _text("Dockerfile") assert ( _text("Dockerfile").splitlines()[1] - == "FROM python:3.11-slim@sha256:" - "b7a9e5f6a93d6d4a31f129bbd4bdee69efccb6ded0fb230d78aafaf37af98377 AS base" + == "FROM python:3.11.18-slim@sha256:" + "db20d8506e2f15b6db39b40b6015ca46bae855dec6dd326d462cfe79ae972893 AS base" ) assert "Verify production image OCR runtime" in ci assert "Verify production image OCR runtime" in release From 3adb658697d06a62b1e3424e59b822c544ee3f03 Mon Sep 17 00:00:00 2001 From: Coding-Dev-Tools <274649000+Coding-Dev-Tools@users.noreply.github.com> Date: Wed, 4 Nov 2026 18:44:42 -0500 Subject: [PATCH 4/5] docs(readme): add Pro and Team upgrade benefits (#321) ## Why upgrade to Pro or Team in the README - Adds a prominent upgrade section after the local feature list. - Explains memory health analytics, scheduled upkeep, encrypted sync, team roles/audit, and the included Jev allowance. - Shows how Jev helps agentic memory: safe vs risky actions, contradictory vs reinforcing memories, supported vs unsupported answers, and complete vs unfinished work. - Adds pricing, no-card trial details, comparison link, and Pro/Team signup links. Tests: documentation contracts, Pro CTA, plugin distribution, and skill package pass; ruff clean. --- README.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/README.md b/README.md index b38847f32..288cecf19 100644 --- a/README.md +++ b/README.md @@ -47,6 +47,18 @@ Connect a coding agent over MCP with the [agent setup guide](https://github.com/ - **Operator control:** Keep the core local and offline-capable, with explicit controls for hosted services and external LLM providers. - **Free Jev on paid plans:** Pro and Team include managed Jev decisions up to 500 calls per person per day, with no personal provider key. +## Why upgrade to Pro or Team + +The local core stays free and offline-capable. Pro and Team add hosted workflows for memory that has to follow you across agents, machines, and teammates: + +- **See memory health:** Analytics surfaces growth, retention, and decay forecasts so you can review what is becoming stale before it affects recall. +- **Keep memory maintained:** Schedule Auto Consolidation and Auto Dreaming. They produce proposals for you to review, and local governance still decides what changes. +- **Sync across machines:** Opt into encrypted Cloud Sync for eligible workspaces with a key you hold. Sync and readable managed processing are separate choices. +- **Give a team an operating picture:** Named seats, admin/member/viewer roles, scoped credentials, and a 30-day account activity log visible to owners and admins. Shared hosted Team memory and hosted MCP are not yet available. +- **Add judgment with Jev:** Pro and Team include up to 500 managed Jev calls per person per day: typed, advisory checks for risky commands, contradictory memories, evidence support, and completion claims. No personal TypeSafe key or overage charge. Jev helps an agent separate safe from risky actions, contradictory from reinforcing memories, supported from unsupported answers, and complete from unfinished work, while permissions and tests stay in charge. + +Pro is $10/month or $100/year for one owner. Team is $20/seat/month or $200/seat/year. Both start with an email-confirmed, no-card trial (7 active days for Pro, 14 active days for Team). [Compare plans](https://github.com/Coding-Dev-Tools/engraphis/blob/main/docs/HOSTED_PLANS.md) · [Start a Pro trial](https://api.engraphis.com/account?plan=pro&interval=monthly&utm_source=engraphis&utm_medium=readme&utm_campaign=pro_conversion&utm_content=readme_upgrade#billing) · [Start a Team trial](https://api.engraphis.com/account?plan=team&interval=monthly&seats=5&utm_source=engraphis&utm_medium=readme&utm_campaign=pro_conversion&utm_content=readme_team_upgrade#billing). + ## Benchmarks The current registered artifact contains three deterministic offline fixture runs. It separates context size, retrieval quality, and grounded decision checks; these small fixtures do not establish general task performance. From 71c4060af5a512f98fa47e3de3d2d51f956f1613 Mon Sep 17 00:00:00 2001 From: coding-dev-tools Date: Thu, 5 Nov 2026 02:31:06 -0500 Subject: [PATCH 5/5] docs(agents): make the advisory discovery path explicit Give the exact task="advisory decision" discovery string and require the canonical decide action check so the documented scenarios actually reach the decision capability. Note the backend prerequisite for remote Jev and refresh the skill checksum. --- .claude-plugin/skill-assets.sha256 | 2 +- docs/AGENT_CONNECT.md | 12 +++++++----- skills/engraphis-memory/SKILL.md | 11 ++++++----- 3 files changed, 14 insertions(+), 11 deletions(-) diff --git a/.claude-plugin/skill-assets.sha256 b/.claude-plugin/skill-assets.sha256 index eb723a43f..24d8b908e 100644 --- a/.claude-plugin/skill-assets.sha256 +++ b/.claude-plugin/skill-assets.sha256 @@ -1,6 +1,6 @@ f6343d92f4c7249ea5789facf391c754537df888f0ca83373acad147e7a41c83 .claude-plugin/marketplace.json bb219dc0cec6364a6c29f3f5fdd4d4aee191840404a61e015a35d63b25d42b38 .claude-plugin/plugin.json -66d5f331076f1989c91af2a03cd88beb64d65780cff2dd173eefec61e091c968 skills/engraphis-memory/SKILL.md +84b3792a88446667ca75893b2dcd30280dd89ee7fb7a88c90bc0b123dc005ccd skills/engraphis-memory/SKILL.md 055655db84af07561d002f0c69744313d8413c39f3e873f941f0fa0b1e76dc66 skills/engraphis-memory/references/CONVENTIONS.md 9d090a03f5b3f36a34d91f66b72c3844591f6915755ac3a6c6ba5f1b16977de5 skills/engraphis-memory/references/SCOPING.md 3e9b71a1730407e1cb7bdd266d84582e90c4d231135abbfbc8c646c0a99c8786 skills/engraphis-memory/references/TOOLS.md diff --git a/docs/AGENT_CONNECT.md b/docs/AGENT_CONNECT.md index 64a1dea8e..ae7faa136 100644 --- a/docs/AGENT_CONNECT.md +++ b/docs/AGENT_CONNECT.md @@ -76,11 +76,13 @@ unless that client has a maintained setup guide and integration test. ## Advisory decisions (Jev) Engraphis exposes its advisory decision engine as a discovered capability rather than a direct -Smart tool. Ask `engraphis_discover_actions` for a decision task, then run the returned `decide` -capability through `engraphis_execute_action`; local heuristics answer by default. Remote Jev is -opt-in per call (`allow_remote=true` plus a `public` or `internal` classification) and uses -TypeSafe BYOK or an included Pro/Team allowance when the hosted service enables it. Decisions -are advice: they never authorize a command, change memory, or certify completion. +Smart tool. Call `engraphis_discover_actions(task="advisory decision")`, confirm the returned +canonical action is `decide`, then run it through `engraphis_execute_action` with its +`schema_digest`; local heuristics answer by default. Remote Jev also needs +`ENGRAPHIS_DECISION_BACKEND=byok|managed` and per-call opt-in (`allow_remote=true` plus a +`public` or `internal` classification), and uses TypeSafe BYOK or an included Pro/Team allowance +when the hosted service enables it. Decisions are advice: they never authorize a command, change +memory, or certify completion. A standalone Jev surface is also available for harnesses that want it: [jev-decision](https://github.com/Coding-Dev-Tools/jev-decision) provides `jev`/`jev-mcp` with diff --git a/skills/engraphis-memory/SKILL.md b/skills/engraphis-memory/SKILL.md index d8ecea2a5..04cfbe578 100644 --- a/skills/engraphis-memory/SKILL.md +++ b/skills/engraphis-memory/SKILL.md @@ -36,11 +36,12 @@ discovery and the validated executors. The decision engine is available through the same gateway and is **advisory only**. When a shell command looks risky, two remembered facts may contradict each other, retrieved evidence looks too weak to answer, or you are about to claim a task is complete, call -`engraphis_discover_actions` with the decision task and run the returned `decide` capability -through `engraphis_execute_action` using the matching `kind` (`guard_command`, -`classify_contradiction`, `verify_support`, `verify_completion`, or `custom`). Local heuristics -answer by default. Remote Jev requires per-call opt-in with `allow_remote=true` and a `public` or -`internal` data classification; without both, nothing leaves the machine. A decision never +`engraphis_discover_actions(task="advisory decision")` and confirm the returned canonical action +is `decide`; then run it through `engraphis_execute_action` with its `schema_digest` and the +matching `kind` (`guard_command`, `classify_contradiction`, `verify_support`, `verify_completion`, +or `custom`). Local heuristics answer by default. Remote Jev also needs +`ENGRAPHIS_DECISION_BACKEND=byok|managed`, per-call opt-in with `allow_remote=true`, and a +`public` or `internal` data classification; without all of those, nothing leaves the machine. A decision never authorizes a command, replaces tests or user approval, or certifies completion. Memory here is **scoped, typed, bi-temporal, and self-maintaining**: writes are deduplicated and