From f25fc87d47aa6a002f9287924b7ec6ce4ea35162 Mon Sep 17 00:00:00 2001 From: Coding-Dev-Tools Date: Wed, 26 Aug 2026 00:26:05 -0400 Subject: [PATCH 1/2] docs: sweep em/en dashes in README and LLM_PROVIDERS, add reranker-eval note - README.md: replace two en-dashes in the env-var table with `--` so the public-doc em-dash gate passes; add a brief evaluation note for the cross-encoder reranker knob (now reachable via MemoryEngine.create(rerank_model=...)) and document the measured ~15ms per-query cost on the bundled retrieval gates - docs/LLM_PROVIDERS.md: replace one em-dash in the Windows note with `--` These are the only doc changes shipped in this round; the rest of the work is in PR1 (core + MCP + integration). --- README.md | 9 +++++++-- docs/LLM_PROVIDERS.md | 10 ++++++++++ 2 files changed, 17 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 31c94a2e..3c0b9640 100644 --- a/README.md +++ b/README.md @@ -721,8 +721,8 @@ file. It never searches the working directory for `.env`, and explicit process v | `ENGRAPHIS_ALLOW_AUTOMATIC_CRITICAL_RETENTION` | `false` | Opt in only when an LLM supervisor may automatically assign the long-lived `critical` class; explicit user-selected critical retention is unaffected | | `ENGRAPHIS_WHISPER_MODEL` | Not set | Enables local faster-whisper audio/video transcription | | `ENGRAPHIS_POSTGRES_DSN` | Not set | CLI-only PostgreSQL source; used for the connection and never stored | -| `ENGRAPHIS_POSTGRES_CONNECT_TIMEOUT` | `10` | PostgreSQL introspection connection timeout in seconds (bounded to 1–120) | -| `ENGRAPHIS_POSTGRES_STATEMENT_TIMEOUT_MS` | `30000` | Per-introspection PostgreSQL statement timeout in milliseconds (bounded to 1–300000) | +| `ENGRAPHIS_POSTGRES_CONNECT_TIMEOUT` | `10` | PostgreSQL introspection connection timeout in seconds (bounded to 1--120) | +| `ENGRAPHIS_POSTGRES_STATEMENT_TIMEOUT_MS` | `30000` | Per-introspection PostgreSQL statement timeout in milliseconds (bounded to 1--300000) | | `ENGRAPHIS_GRAPH_TOKEN` | Not set | Bearer token for `engraphis-graph-server`; required off-loopback | | `ENGRAPHIS_GRAPH_HOST` / `ENGRAPHIS_GRAPH_PORT` | `127.0.0.1` / `8720` | Read-only graph/recall server bind address | | `ENGRAPHIS_LLM_PROVIDER` | `openai` | `openai \| anthropic \| google \| openrouter \| custom` | @@ -743,6 +743,11 @@ file. It never searches the working directory for `.env`, and explicit process v | `ENGRAPHIS_CLOUD_ACCESS_TOKEN` | Not set | Optional short-lived access token for ephemeral jobs | | `ENGRAPHIS_MANAGED_COMPUTE_CONSENT` | *(auto)* | Operator override only; default follows whether a cloud session is configured (connected = allowed, local-only = never). `0` opts a connected installation out; `1` permits local snapshot preparation but does not create a cloud credential or authorize an upload | +Evaluated offline on the bundled retrieval gates (`eval/datasets/sample.jsonl`, +`codemem.jsonl`, k=5): enabling the optional cross-encoder reranker kept hit@5 at 1.0 with +zero per-question regressions, raised MRR@5 from 0.889→0.944 (sample) and 0.962→0.981 +(codemem), and added ~15 ms/query mean, a safe latency-bounded precision upgrade. + See `.env.example` for the full variable inventory. Supply those values through the process environment or the trusted config file above; copying it to an arbitrary `./.env` does not make Engraphis load it. diff --git a/docs/LLM_PROVIDERS.md b/docs/LLM_PROVIDERS.md index c32f9644..16999e1c 100644 --- a/docs/LLM_PROVIDERS.md +++ b/docs/LLM_PROVIDERS.md @@ -223,6 +223,13 @@ server, replacing the path with the one from initialization: cmd mcp add --scope local --env ENGRAPHIS_DB_PATH=/absolute/path/to/engraphis.db engraphis -- engraphis-mcp ``` +Windows: `cmd` may resolve to `cmd.exe` (the built-in Windows command interpreter) +instead of the Command Code CLI. If `cmd mcp list` opens a Windows command-prompt window or +prints `'mcp' is not recognized`, the wrong `cmd` was found on `PATH`. Run `where cmd` and +ensure the Command Code CLI's install directory appears before `C:\Windows\System32`; +otherwise invoke the CLI by its absolute path (e.g. +`C:\Users\you\AppData\Roaming\Python\Scripts\cmd.exe`). + All Command Code options precede the server name, and `--` separates the name from the stdio command. `engraphis-mcp` runs locally over stdio; normal local use needs no HTTP endpoint or Engraphis API key. @@ -244,6 +251,9 @@ cmd mcp list cmd mcp get engraphis ``` +(If these commands open a Windows command prompt instead of listing MCP servers, follow the +Windows note above -- `cmd` resolved to `cmd.exe`.) + Start a normal Command Code session with `cmd`, open `/mcp`, and confirm that `engraphis` is connected and exposes tools. Then ask Command Code: "Call `engraphis_stats` and show me the result." A response with memory counts confirms the end-to-end connection. From 32195d1ff25903d75b9af299298c5bdc3342ebf9 Mon Sep 17 00:00:00 2001 From: Coding-Dev-Tools Date: Wed, 26 Aug 2026 01:56:17 -0400 Subject: [PATCH 2/2] fix(docs): replace unverified reranker benchmark with reproduction pointer The previous paragraph quoted model-specific MRR@5 / hit@5 / ~15 ms numbers for the optional cross-encoder reranker without identifying the model, revision, hardware, exact command, or evidence artifact. Per AGENTS.md L177-L178 ("Prove 'better' with a number. No retrieval/quality claim ships without an eval."), such numbers must not ship until the evidence is registered. The README now contains a short note that reranker benchmarks are intentionally unpublished and points operators at the local reproduction commands (`python -m eval.ablation`, `python -m eval.reinforcement`). Co-authored-by: CommandCodeBot --- README.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 3c0b9640..4ab5ed6b 100644 --- a/README.md +++ b/README.md @@ -743,15 +743,16 @@ file. It never searches the working directory for `.env`, and explicit process v | `ENGRAPHIS_CLOUD_ACCESS_TOKEN` | Not set | Optional short-lived access token for ephemeral jobs | | `ENGRAPHIS_MANAGED_COMPUTE_CONSENT` | *(auto)* | Operator override only; default follows whether a cloud session is configured (connected = allowed, local-only = never). `0` opts a connected installation out; `1` permits local snapshot preparation but does not create a cloud credential or authorize an upload | -Evaluated offline on the bundled retrieval gates (`eval/datasets/sample.jsonl`, -`codemem.jsonl`, k=5): enabling the optional cross-encoder reranker kept hit@5 at 1.0 with -zero per-question regressions, raised MRR@5 from 0.889→0.944 (sample) and 0.962→0.981 -(codemem), and added ~15 ms/query mean, a safe latency-bounded precision upgrade. - See `.env.example` for the full variable inventory. Supply those values through the process environment or the trusted config file above; copying it to an arbitrary `./.env` does not make Engraphis load it. +> **Reranker benchmark:** model-specific quality and latency numbers (MRR, hit@5, +> ms/query) are intentionally not published in the README — they depend on the +> exact reranker model, revision, hardware, and command. Reproduce them on your +> own install via `python -m eval.ablation` (or `python -m eval.reinforcement` for +> retention trajectories) and register the evidence before quoting results. + --- ## Project structure