Skip to content
Open
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 @@ -29,7 +29,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 = 17`) | `engraphis_v1.db` |
| Data | new v2 schema (`SCHEMA_VERSION = 18`) | `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.
Expand Down Expand Up @@ -210,7 +210,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 = 17`)
## 5. Data model cheat-sheet (`core/interfaces.py`, `core/schema.py` — `SCHEMA_VERSION = 18`)

- **Scope hierarchy:** `workspace → repo → session → memory`. Scopes: `session|repo|workspace|user`.
- **Bi-temporal validity on every record:** world-time `valid_from/valid_to` +
Expand Down
8 changes: 4 additions & 4 deletions BENCHMARKS.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,12 +11,12 @@ For the locked operator sequence for a public canonical run, see
Every exact public aggregate retained below comes from the checked-in, public-safe
[`offline-fixtures-v1.json`](docs/benchmark-evidence/offline-fixtures-v1.json) artifact. Its
SHA-256 is
`8a74e9f48e25f33d625d4cc5c1b14fec3055891944adccf615c440e84e4b0255`, also recorded in the
`4d5056d137182ae5cf116c5d59af18b38a7a0ed7731885e9597f63e549cb46b7`, 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
`4d7e40607319cd4bf8caee3897f1e416dbe5b81998b37a7e4839409ee2923537`. The artifact defines
`f5544b56f009b2fc16dbae992039971899daf2b0095ee8d15bad5914c7f399a9`. 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 Down Expand Up @@ -72,8 +72,8 @@ frontier-model QA score.
JSON-safe schema. Payload proxies are sampled once per question, independently of the number
of timed iterations; they are not serialized MCP envelopes or transport responses. In the
registered CodeMem run, 26 payload samples total **23,810** full-proxy
`engraphis.regex.v1` tokens versus **10,202** compact-proxy tokens, avoiding **13,608** proxy
tokens (**57.15% lower**), while 260 recalls are timed. Packed context across the same 26
`engraphis.regex.v1` tokens versus **10,982** compact-proxy tokens, avoiding **12,828** proxy
tokens (**53.88% lower**), while 260 recalls are timed. Packed context across the same 26
samples averages **85.38** tokens and reaches **108** under a 1,500-token cap; Recall@5,
hit@5, and answer-token recall remain 1.000. These aggregates are evidence ID
`offline-performance` in the registry above. `--filler-memories`, `--candidate-k`, and
Expand Down
19 changes: 19 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,25 @@
All notable changes to Engraphis are documented here. Format loosely follows
[Keep a Changelog](https://keepachangelog.com/); versions use SemVer.

## [Unreleased]

- Added schema 18 content-free command receipts and cross-process source revalidation for
corrections, approvals, promotions and merges. Combined memory revisions have expected
versions, operation IDs, atomic metadata/history, and typed conflicts.
- Sync publication uses current canonical state and generation-aware repair; delayed work
cannot restore erased vectors. Native-index failures roll back canonical changes.
- Context retains distinct scoped evidence; synthesis falls back when complete source
units, titles, values or conditions are lost. Answer coverage defaults to unknown.
- Added project-aware memory workflows and paginated record history.
- Library cursors survive unrelated activity and work across processes. File-backed
browsing uses bounded live read snapshots; completed graph migrations are not
repeated at ordinary startup.
- Ask separates answer/preview retries, cancellation and answer coverage. Home uses
actionable review state; Explore pauses hidden views through existing renderers.
- Added content-free diagnostics and build/capability information, strict coding
acceptance validation and a file-backed independent-process capacity harness.
These provide measurement infrastructure, not verified 100k capacity claims.

## [1.7.2] - 2026-09-05

### Added
Expand Down
2 changes: 2 additions & 0 deletions MANIFEST.in
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,8 @@ recursive-include engraphis/dashboard_assets/vendor *
include engraphis/commercial_manifest.json
include LICENSE NOTICE README.md CHANGELOG.md BENCHMARKS.md
include docs/RECALL_RECOVERY.md
include docs/REWORK_EXECUTION.md docs/ENGINE_CAPACITY_PROTOCOL.md docs/CODING_ACCEPTANCE_CORPUS.md
include docs/PAID_EVALUATION_PROPOSAL.md
include docs/DOCUMENT_IMPORT.md docs/OBSIDIAN_IMPORT.md
include docs/images/context-efficiency.svg
include pyproject.toml
Expand Down
13 changes: 8 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ by default, or accept an explicit workspace plus optional `from_ts`, `to_ts`, an
`release_version` filters.

<p align="center">
<img src="https://raw.githubusercontent.com/Coding-Dev-Tools/engraphis/main/docs/images/context-efficiency.svg" alt="Dark chart of local measurements and deterministic fixtures, including a local LoCoMo diagnostic marked with an asterisk. Cross-session handoff satisfaction rises from 3 of 15 queries with the last memories to 15 of 15 with proactive ranking or a consolidated summary. Intent-layered graph routing rises from 0 of 3 to 3 of 3 correct top-1 targets, and two-hop graph recall rises from 0 of 3 with one-hop expansion to 3 of 3 with Personalized PageRank. Consolidation-aware ranking selects the expected digest in 2 of 2 summary cases instead of 0 of 2 for the baseline. Structure-aware chunks reduce context from 740.3 to 214.3 tokens and the smallest evidence-holding memory from 162.2 to 42.4 tokens. A compact JSON-shape proxy uses 10,202 rather than 23,810 tokens. Grounded recall makes 10 of 10 correct decisions and packed context averages 85.38 tokens under a 1,500-token cap." width="100%">
<img src="https://raw.githubusercontent.com/Coding-Dev-Tools/engraphis/main/docs/images/context-efficiency.svg" alt="Dark chart of local measurements and deterministic fixtures, including a local LoCoMo diagnostic marked with an asterisk. Cross-session handoff satisfaction rises from 3 of 15 queries with the last memories to 15 of 15 with proactive ranking or a consolidated summary. Intent-layered graph routing rises from 0 of 3 to 3 of 3 correct top-1 targets, and two-hop graph recall rises from 0 of 3 with one-hop expansion to 3 of 3 with Personalized PageRank. Consolidation-aware ranking selects the expected digest in 2 of 2 summary cases instead of 0 of 2 for the baseline. Structure-aware chunks reduce context from 740.3 to 214.3 tokens and the smallest evidence-holding memory from 162.2 to 42.4 tokens. A compact JSON-shape proxy uses 10,982 rather than 23,810 tokens. Grounded recall makes 11 of 11 correct decisions and packed context averages 85.38 tokens under a 1,500-token cap." width="100%">
<br>
<sup>Less repeated history means more room for the task, tools, and useful evidence.</sup>
</p>
Expand Down Expand Up @@ -73,13 +73,13 @@ its counting boundary explicit.
|---|---|---|---|
| Retrieved top-5 memory content, averaged per question | Whole documents: **740.3** tokens → structure-aware chunks: **214.3** tokens | **526.0 fewer tokens per question** (**71.1% lower**, about **3.5× smaller**) | Recall@5 **1.000** in both modes across 6 documents and 18 questions |
| Smallest returned memory that contains the reference evidence | Whole documents: **162.2** tokens → chunks: **42.4** tokens | **119.8 fewer tokens to evidence** (**73.9% lower**, about **3.8× smaller**) | The same 18 questions had a returned evidence-holding memory in both modes |
| Full versus compact recall payload proxy across one 26-question pass within a 260-timed-recall CodeMem run | Full proxy: **23,810** `engraphis.regex.v1` tokens → compact proxy: **10,202** tokens | **13,608 proxy tokens avoided** (**57.15% lower**) | 26 payload samples; 260 timed recalls; Recall@5, hit@5, and answer-token recall all **1.000** |
| Full versus compact recall payload proxy across one 26-question pass within a 260-timed-recall CodeMem run | Full proxy: **23,810** `engraphis.regex.v1` tokens → compact proxy: **10,982** tokens | **12,828 proxy tokens avoided** (**53.88% lower**) | 26 payload samples; 260 timed recalls; Recall@5, hit@5, and answer-token recall all **1.000** |
| Packed prompt-context usage in the same 26-question CodeMem sample pass | Hard budget: **1,500** tokens; observed mean: **85.38**; observed maximum: **108** | A hard cap prevents a recall from exceeding its configured context budget | This is usage accounting, not a before/after savings comparison |

These values are evidence IDs `offline-chunking` and `offline-performance` in
[`offline-fixtures-v1.json`](https://github.com/Coding-Dev-Tools/engraphis/blob/main/docs/benchmark-evidence/offline-fixtures-v1.json),
SHA-256
`8a74e9f48e25f33d625d4cc5c1b14fec3055891944adccf615c440e84e4b0255`.
`4d5056d137182ae5cf116c5d59af18b38a7a0ed7731885e9597f63e549cb46b7`.
[`BENCHMARKS.md`](https://github.com/Coding-Dev-Tools/engraphis/blob/main/BENCHMARKS.md#public-numeric-evidence-registry)
records the matching suite digest, exact commands, and per-command config digests. External,
model-dependent, consolidation, productivity, and latency results remain unpublished until the
Expand Down Expand Up @@ -872,10 +872,13 @@ grant. See [`docs/LICENSING.md`](https://github.com/Coding-Dev-Tools/engraphis/b

### Reliability implementation candidate

The current source uses schema 17 for durable, content-free vector-index repair.
The current source uses schema 18 for durable, content-free vector-index repair and
atomic memory-command receipts. Upgrades use the existing verified-backup migration path.
The [rework execution register](https://github.com/Coding-Dev-Tools/engraphis/blob/main/docs/REWORK_EXECUTION.md) records the current findings,
compatibility decisions, acceptance evidence, remaining work and recovery procedure.
See [the reliability program](https://github.com/Coding-Dev-Tools/engraphis/blob/main/docs/RELIABILITY_PROGRAM.md) for exact implementation,
validation, migration and release boundaries. Managed processing now requires explicit
workspace approval in Manage → Settings. Existing installations start with readable
workspace approval in Settings. Existing installations start with readable
uploads paused until confirmed; connecting an account does not grant approval.

For setup diagnostics use `engraphis-init --check --json`. New configurations get an
Expand Down
Loading