Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -225,8 +225,8 @@ These are pure, unit-tested functions — change them only with a corresponding
`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`, `memory_tombstones`, `source_vaults`,
`source_imports`, `source_import_items`, `memory_closures`, `schema_migrations`,
`migration_executions`.
`source_imports`, `source_import_items`, `memory_closures`, `vector_visibility_state`,
`browse_state`, `browse_scope_revisions`, `schema_migrations`, `migration_executions`.
- **Local document sources:** source collections are scope-bound, resumable manifests. Their
paths, digests, and import state are provenance; source folders never create implicit memory
scopes. `kind="documents"` is the source-neutral adapter, while `kind="obsidian"` retains
Expand Down
25 changes: 16 additions & 9 deletions BENCHMARKS.md
Original file line number Diff line number Diff line change
Expand Up @@ -94,14 +94,14 @@ interpretation and do not count as additional benchmark-quality gains.
### Public numeric evidence registry

Every exact public aggregate retained below comes from the checked-in, public-safe
[`offline-fixtures-connect-verify-20261117.json`](docs/benchmark-evidence/offline-fixtures-connect-verify-20261117.json) artifact. Its
[`offline-fixtures-perf-vector-20261118.json`](docs/benchmark-evidence/offline-fixtures-perf-vector-20261118.json) artifact. Its
SHA-256 is
`28f0fb97bb043446418c838b7db10a6a794b6e99ab5d621c1e6db04215df1737`, also recorded in the
`91362de33eebd74bb6d28dd24025f57ad029c995d0bf68e44d5561c0b6c8e9bb`, also recorded in the
adjacent `.sha256` file. The artifact contains no raw questions, answers, prompts, customer data,
or per-record content fingerprints.

The fixture-suite digest is
`d95d8839c1260db162861411ab0a84d20273b587d2b7001362ac6fec4b1434eb`. The artifact defines
`3cdb1315833c982e8d6a774be137f04d8c14018e7ee4d90c4ef05a1bfc2ad174`. The artifact defines
the digest algorithm and records the SHA-256 of every suite and dataset file. Each evidence ID
also binds its exact command through `sha256(UTF-8 exact command)`:

Expand All @@ -117,9 +117,9 @@ The canonical chart aliases are regenerated from that new artifact and carry its
historical per-run artifacts and their preserved chart bytes remain unchanged. The current
PNG views were freshly rendered from the registered artifact SVG via Google Chrome for Testing 156.0.8078.4
headless shell on Windows at each SVG canvas size, with embedded artifact and SVG checksums.
The fresh evaluator run used Windows CPython 3.11.17 and NumPy 2.4.6. Its 591-file manifest
binds the producer after adding pre-write hosted connection and Jev quota verification in
`engraphis/device_connect.py` atop the 1.7.10+ fixes: Command Code file-guard tool
The fresh evaluator run on 2026-11-18 UTC used Windows CPython 3.11.17 and NumPy 2.4.6. Its 591-file manifest
binds the producer after adding the trigger-invalidated vector visibility revision, bounded NumPy
matrix cache, and `remember_many` embedding deduplication atop `engraphis/device_connect.py` and the 1.7.10+ fixes: Command Code file-guard tool
ids, fail-closed hook errors, symlink-then-parent and Windows alias targets, the linear
Spec Studio heading pattern, closure-limit and browse-version handling, the equal-start
supersede guard, bounded history candidate windows for `why` and `timeline`, raw-path UNC/device
Expand All @@ -135,10 +135,12 @@ retrieval-quality improvement. It does not qualify browser behavior, hosted serv
external models, or provider billing. The registered artifact was produced with:

```bash
python -m scripts.export_offline_evidence --output docs/benchmark-evidence/offline-fixtures-connect-verify-20261117.json
python -m scripts.export_offline_evidence --output docs/benchmark-evidence/offline-fixtures-perf-vector-20261118.json
```

The earlier release-review predecessors,
[`offline-fixtures-connect-verify-20261117.json`](docs/benchmark-evidence/offline-fixtures-connect-verify-20261117.json)
(SHA-256 `28f0fb97bb043446418c838b7db10a6a794b6e99ab5d621c1e6db04215df1737`),
[`offline-fixtures-paid-plans-20261109.json`](docs/benchmark-evidence/offline-fixtures-paid-plans-20261109.json)
(SHA-256 `d787cc2a6af8de86442b56833b0fdd5654b548779403b5a03c48bc9e7ef4f760`),
[`offline-fixtures-automatic-browser-access-20261031.json`](docs/benchmark-evidence/offline-fixtures-automatic-browser-access-20261031.json)
Expand Down Expand Up @@ -206,13 +208,13 @@ grounded checks in separate panels; provider billing and MCP transport are not m
the SVG and matching PNG with:

```bash
python scripts/render_benchmark_report.py --report docs/benchmark-evidence/offline-fixtures-connect-verify-20261117.json --output docs/images/context-efficiency.svg --png-output docs/images/context-efficiency.png
python scripts/render_benchmark_report.py --report docs/benchmark-evidence/offline-fixtures-perf-vector-20261118.json --output docs/images/context-efficiency.svg --png-output docs/images/context-efficiency.png
```

The companion examples are also generated from that artifact with:

```bash
python -m scripts.render_benchmark_examples --report docs/benchmark-evidence/offline-fixtures-connect-verify-20261117.json --output docs/images/evidence-backed-agent-examples.svg --png-output docs/images/evidence-backed-agent-examples.png
python -m scripts.render_benchmark_examples --report docs/benchmark-evidence/offline-fixtures-perf-vector-20261118.json --output docs/images/evidence-backed-agent-examples.svg --png-output docs/images/evidence-backed-agent-examples.png
```
The historical-to-executable mapping is in
[`docs/BENCHMARK_CHANGE_COVERAGE.md`](docs/BENCHMARK_CHANGE_COVERAGE.md).
Expand Down Expand Up @@ -246,6 +248,11 @@ frontier-model QA score.
query_image=None)` memory interface; it does not download data or call a model.
- **Grounded**: `eval/grounded.py`: answerable → cite, off-topic → abstain. Exact fixture
outcomes are evidence ID `offline-grounded` in the registry above.
- **Direct vector search (`eval/vector_scale.py`, non-registered machine timing, `warmups=1`)**:
Windows CPython 3.11.17 / NumPy 2.4.6 (`--backend numpy --sizes 1000,10000 --dim 256 --queries 20 --iterations 3`),
`ENGRAPHIS_VECTOR_CACHE_BYTES=0` vs 64 MiB cache (`setup_included_in_latency: false`):
p50 `16.234 ms -> 0.194 ms` (`p95 21.306 ms -> 0.303 ms`) at 1,000 vectors, `80.929 ms -> 2.448 ms`
(`p95 96.132 ms -> 3.008 ms`) at 10,000 vectors (`result_ids_sha256` `e1b11010...`, `4676dc67...`).
- **Chunking (quality per token)**: `eval/chunking_eval.py` over `eval/datasets/longdoc.jsonl`
ingests a multi-topic corpus twice: once as one memory per document (`whole`) and once with
sub-file `ChunkingExtractor` (`chunked`), then queries both through the real recall pipeline.
Expand Down
5 changes: 5 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,11 @@ All notable changes to Engraphis are documented here. Format loosely follows

## [Unreleased]

- Add a local, trigger-invalidated `vector_visibility_state` revision and 64 MiB `NumpyVectorIndex`
cache across temporal windows, dedupe `MemoryEngine.remember_many`, install `idx_mem_ingested`
(additive v19 repair, no `SCHEMA_VERSION` bump or second `.pre-migration-v19.bak`; rollback drops
all nine `trg_vector_vis_*` triggers before `vector_visibility_state` / `idx_mem_ingested`), and
set SQLite page cache to ~16 MiB/connection (plus opt-in `ENGRAPHIS_SQLITE_MMAP=1`).
- Add one checked-in entitlement contract as the read-only plan→feature mirror, and fail the
release gate when it drifts from the private hosted contract. Local workspace export stays
free; a server grant this build cannot render is reported instead of silently dropped.
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -91,7 +91,7 @@ Pro is $10/month or $100/year for one owner. Team is $20/seat/month or $200/seat
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.

<p align="center">
<img src="https://raw.githubusercontent.com/Coding-Dev-Tools/engraphis/99af3855bd6b685cbac4a4489b44b3c374129053/docs/images/context-efficiency.svg" alt="Three registered offline fixtures: structure-aware chunking reduced mean retrieved context from 740.3 to 214.3 tokens per question (71.1%, 18 questions); the serialized JSON-shape proxy fell from 24,590 to 11,138 tokens across 26 payload samples and 260 recalls. Candidate and packed retrieval quality (Recall@5, Hit@5, and answer-token recall) are shown separately (each 1.000). Grounded checks show 5/5 answerable queries grounded and 6/6 abstention queries rejected, including a 1/1 quarantined-evidence probe; 11/11 decisions were correct. MCP transport and provider billing were not measured. Artifact SHA-256 prefix 28f0fb97bb04; see the benchmark guide for the full checksum." width="100%">
<img src="https://raw.githubusercontent.com/Coding-Dev-Tools/engraphis/99af3855bd6b685cbac4a4489b44b3c374129053/docs/images/context-efficiency.svg" alt="Three registered offline fixtures: structure-aware chunking reduced mean retrieved context from 740.3 to 214.3 tokens per question (71.1%, 18 questions); the serialized JSON-shape proxy fell from 24,590 to 11,138 tokens across 26 payload samples and 260 recalls. Candidate and packed retrieval quality (Recall@5, Hit@5, and answer-token recall) are shown separately (each 1.000). Grounded checks show 5/5 answerable queries grounded and 6/6 abstention queries rejected, including a 1/1 quarantined-evidence probe; 11/11 decisions were correct. MCP transport and provider billing were not measured. Artifact SHA-256 prefix 91362de33eeb; see the benchmark guide for the full checksum." width="100%">
<br>
<sup>Three offline fixtures separate context reduction, candidate and packed retrieval quality, and grounded behavior. The chart shows the artifact checksum prefix; see the benchmark guide for the full checksum and reproduction steps.</sup>
</p>
Expand Down
2 changes: 2 additions & 0 deletions docs/CONFIGURATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,8 @@ control-plane, relay, compute, and worker implementations are private services.
| `ENGRAPHIS_ENV_FILE` | `~/.engraphis/config.env` | Optional trusted config leaf selected before trusted values load. Its bounded dependency-free parser performs no interpolation. An explicit value must be an absolute path to an owner-private regular file; arbitrary working-directory `.env` files are ignored. |
| `ENGRAPHIS_DB_PATH` | Source: `<repo>/engraphis.db`; installed: platform user-data directory | SQLite database file. Installed defaults are `%LOCALAPPDATA%\engraphis\engraphis.db` (Windows), `~/Library/Application Support/engraphis/engraphis.db` (macOS), and `$XDG_DATA_HOME/engraphis/engraphis.db` or `~/.local/share/engraphis/engraphis.db` (Linux). The environment variable overrides every default; a relative value is resolved from the trusted `~/.engraphis/config.env` directory so launch CWD cannot select a different workspace database. |
| `ENGRAPHIS_SQLITE_DURABILITY` | `durable` | Writable file databases use WAL and FULL commit synchronization. Explicit `balanced` selects NORMAL, which can lose recent acknowledged writes after OS/power failure. Effective settings appear in diagnostics; see [SQLite durability](https://github.com/Coding-Dev-Tools/engraphis/blob/main/docs/SQLITE_DURABILITY.md). |
| `ENGRAPHIS_SQLITE_MMAP` | `0` | Opt-in 64 MiB memory-mapped SQLite reads (`1`, `true`, or `yes`) for local plaintext databases; skipped for SQLCipher and off by default for synced/shared folders. |
| `ENGRAPHIS_VECTOR_CACHE_BYTES` | `67108864` | Maximum byte budget for the in-process `NumpyVectorIndex` decoded matrix cache (default 64 MiB; `0` disables retention). |
| `ENGRAPHIS_HOST` | `127.0.0.1` | Server bind address |
| `ENGRAPHIS_PORT` | `8700` | Dashboard port. A platform-injected `$PORT` (Railway/Fly/Heroku) takes precedence over this value for the dashboard bind; Compose pins both to `ENGRAPHIS_COMPOSE_PORT` so the mapping stays in sync |
| `ENGRAPHIS_SERVICE_MODE` | `customer` | The public package supports only `customer`; hosted vendor, relay, compute, and worker roles are not distributed here |
Expand Down
Loading
Loading