Skip to content
Draft
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
2 changes: 1 addition & 1 deletion .claude-plugin/marketplace.json
Original file line number Diff line number Diff line change
Expand Up @@ -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.7.9"
"version": "1.7.10"
}
]
}
2 changes: 1 addition & 1 deletion .claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "engraphis-memory",
"version": "1.7.9",
"version": "1.7.10",
"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",
Expand Down
4 changes: 2 additions & 2 deletions .claude-plugin/skill-assets.sha256
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
c1d184247775c8b3bf4d3f185d54fcac983aca8c54638a05d85b21e20db3ae7c .claude-plugin/marketplace.json
c5d0c26f28c9ee14092f9deaf24c98dd8bef49d971fef2b7a537ffb1ab9f2887 .claude-plugin/plugin.json
8da43b92bc5ece3e7bdc63779713f76552a7bcd46adaf5ff12c0427dbfad98ae .claude-plugin/marketplace.json
b1adecc8e456a3dbe168adb7adc6a9c7c7ae63429d38b88c02722eaf293a9fba .claude-plugin/plugin.json
aeee7a94671ceb306fe2d24c5acc9f2d96ad8a8e7410536566799eea6265f080 skills/engraphis-memory/SKILL.md
055655db84af07561d002f0c69744313d8413c39f3e873f941f0fa0b1e76dc66 skills/engraphis-memory/references/CONVENTIONS.md
9d090a03f5b3f36a34d91f66b72c3844591f6915755ac3a6c6ba5f1b16977de5 skills/engraphis-memory/references/SCOPING.md
Expand Down
7 changes: 7 additions & 0 deletions .gitattributes
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,16 @@
*.pyd binary
*.so binary
*.dll binary
*.py text eol=lf
.github/workflows/*.yml text eol=lf
.github/workflows/*.yaml text eol=lf
*.sh text eol=lf
# Frozen corpus/evidence manifests hash exact bytes, including executable oracles.
eval/datasets/** text eol=lf
eval/artifacts/** text eol=lf
# Historical reports include both LF and CRLF snapshots; preserve their signed bytes.
docs/benchmark-evidence/** -text
engraphis/**/vendor/*.js text eol=lf
deploy/*.lock text eol=lf
deploy/*.licenses.json text eol=lf
.claude-plugin/*.json text eol=lf
Expand Down
8 changes: 8 additions & 0 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -94,6 +94,10 @@ jobs:
python -m eval.ablation
python -m eval.reinforcement
python -m eval.adversarial_memory_security
python -m eval.grounded
python -m eval.code_arm
python -m eval.spec_crawl
python -m eval.evidence_contracts
python -m pip_audit --local --skip-editable

- name: Capture the exact build environment and Python SBOM
Expand Down Expand Up @@ -344,6 +348,10 @@ jobs:
python -m eval.ablation
python -m eval.reinforcement
python -m eval.adversarial_memory_security
python -m eval.grounded
python -m eval.code_arm
python -m eval.spec_crawl
python -m eval.evidence_contracts

artifact-core-py39:
name: Python 3.9 installed release artifacts
Expand Down
13 changes: 10 additions & 3 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/` |
| Data | new v2 schema (`SCHEMA_VERSION = 18`) | `engraphis_v1.db` |
| Data | new v2 schema (`SCHEMA_VERSION = 19`) | `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 @@ -59,6 +59,7 @@ python -m eval.reinforcement # bounded re
python -m eval.adversarial_memory_security # prompt/graph boundary
python -m eval.grounded # grounded-abstain decision gate
python -m eval.code_arm # coding-agent arm gate
python -m eval.spec_crawl # specification and memory-audit gate
python -m eval.spec_crawl # agent spec quality & prompt crawl gate
pyright # core + backends typecheck

Expand Down Expand Up @@ -211,7 +212,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 = 18`)
## 5. Data model cheat-sheet (`core/interfaces.py`, `core/schema.py` — `SCHEMA_VERSION = 19`)

- **Scope hierarchy:** `workspace → repo → session → memory`. Scopes: `session|repo|workspace|user`.
- **Bi-temporal validity on every record:** world-time `valid_from/valid_to` +
Expand All @@ -224,7 +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`, `schema_migrations`.
`source_imports`, `source_import_items`, `memory_closures`, `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 All @@ -233,6 +235,11 @@ These are pure, unit-tested functions — change them only with a corresponding
- **Erasure markers contain no memory content.** `memory_tombstones.export_class` is strictly
`never_export|remote_erasure`; only `remote_erasure` may cross a sync boundary.
- **Vectors are stored L2-normalized** so cosine similarity == dot product.
- **Closure history is append-only:** `memory_closures` preserves each known closure.
Historical visibility uses the earliest endpoint known at `known_at`; the scalar
`valid_to` pair is only the current compatibility summary. Sync v4 transports the
observation union; earlier clients must upgrade before receiving v4 bundles.
Legacy observations with no recorded knowledge time remain visible at every knowledge anchor.

---

Expand Down
63 changes: 51 additions & 12 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-pr260-nested-uri-redaction-runtime-20261018-e2ebfb06550f.json`](docs/benchmark-evidence/offline-fixtures-pr260-nested-uri-redaction-runtime-20261018-e2ebfb06550f.json) artifact. Its
[`offline-fixtures-pr270-guard-installer-20261020.json`](docs/benchmark-evidence/offline-fixtures-pr270-guard-installer-20261020.json) artifact. Its
SHA-256 is
`434ec054dff38104a553ddb88b38a983c97227491e92ba482a7f3cd4ff5b560b`, also recorded in the
`047cbdfee604c54c2fe211f7cac54a532563ceecadc310f368dec331bf443ce3`, 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
`28a67b9a2b182aaff93603e5631d2bf803538f5b81a67767effeb54f456c29fa`. The artifact defines
`8607a2a500065adf7bd72f85e4c35462b9958ddfdbb34ef53896360fe2e1d86d`. 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 @@ -112,16 +112,53 @@ also binds its exact command through `sha256(UTF-8 exact command)`:
| `offline-grounded` | `python -m eval.grounded` | `590442e51e3642c10489165759919dc86ffac62c182937330c153e7f8d5fc26f` |

The source manifest covers every Python file under `engraphis/` and `eval/`, the two
fixture datasets, and the official exporter. Each rerun must use a new artifact and chart
basename because existing evidence is immutable. This run used Python 3.12.14 and NumPy 2.5.4;
the charts were rendered with CairoSVG 2.9.1. Its 587-file manifest binds the Python
producer. Runtime commit `e2ebfb06550fdcda0eb03590aecd9cf5e27a6dbc` also identifies
the CLI and Dashboard source outside that manifest. The registered artifact was produced with:
fixture datasets, and the official exporter. Each rerun must use a new artifact basename.
The canonical chart aliases are regenerated from that new artifact and carry its checksum;
historical per-run artifacts and their preserved chart bytes remain unchanged. The current
PNG views were freshly rendered from the registered artifact with CairoSVG 2.9.1 and
Cairo 1.18.4 on Linux at each SVG canvas size, using sealed LiberationSans and DejaVuSans
fonts and embedded artifact and SVG checksums. The fresh evaluator run used Linux
CPython 3.12.14 and NumPy 2.4.6. Its 588-file manifest binds the producer after the
policy-file parent-directory canonicalization fix. The hook installer fix, dashboard
assets, tests, documentation, and generated images are outside this producer manifest.
The three measured fixture results are unchanged; this rerun establishes current
source and render provenance without claiming a retrieval-quality improvement. It does
not qualify browser behavior, hosted services, external models, or provider billing.
The registered artifact was produced with:

```bash
python -m scripts.export_offline_evidence --output docs/benchmark-evidence/offline-fixtures-pr260-nested-uri-redaction-runtime-20261018-e2ebfb06550f.json
python -m scripts.export_offline_evidence --output docs/benchmark-evidence/offline-fixtures-pr270-guard-installer-20261020.json
```

The earlier [browser-session snapshot artifact](docs/benchmark-evidence/offline-fixtures-reconciled-browser-session-20261019.json)
remains bound to SHA-256 `b3a65eea3559a1b994e6e4b81ade81db914ce1ae94b947ed7454e5cf8550998f` and its original
CPython 3.11.17 / NumPy 2.4.6 execution and Playwright Chromium 156.0.8078.4 rendering.
It predates the policy-parent canonicalization fix and remains historical and unchanged;
its results and rendered bytes are not relabeled as this fresh run.

The earlier [Automation snapshot artifact](docs/benchmark-evidence/offline-fixtures-reconciled-automation-20261019.json)
remains bound to SHA-256 `694765e499a089bdcc00ed0b2b6f763bd3f5606f0f4cb6aa3061338d2cb012a1`. It predates the browser-session
cookie-response correction and remains unchanged.

The earlier [protected-path snapshot artifact](docs/benchmark-evidence/offline-fixtures-reconciled-path-guard-20261019.json)
remains bound to SHA-256 `10d5c8111647190479aa7dd16831e5e741873d43fc9385190e1f195937a4084d`. It predates the Automation
policy and dashboard recovery corrections and remains unchanged.

The earlier [canonical LF snapshot artifact](docs/benchmark-evidence/offline-fixtures-reconciled-canonical-lf-20261019.json)
remains bound to SHA-256 `26d75c8a38127edbc51e6c51792cd85f04bf707c32bb1ff8d7c33ae95fb4c34d`. It predates the Windows protected-path
case-matching correction and remains unchanged.

The earlier [reconciled snapshot artifact](docs/benchmark-evidence/offline-fixtures-reconciled-release-20261019.json)
remains bound to SHA-256 `4de6ca8011e45146d98d855cedca6f7e3f84d8c7e75852405f36ac0f74e96f6d`.
It predates canonical LF normalization of the two Python producer files and remains unchanged.

The historical [governed-history artifact](docs/benchmark-evidence/offline-fixtures-governed-history-20261018.json)
remains bound to SHA-256 `23203af13a30a78df9f2bf849f2cefdad1c426a9f494ebb0128abd5fa6e19ce9`.
The separate [main-branch runtime artifact](docs/benchmark-evidence/offline-fixtures-pr260-nested-uri-redaction-runtime-20261018-e2ebfb06550f.json)
remains bound to SHA-256 `434ec054dff38104a553ddb88b38a983c97227491e92ba482a7f3cd4ff5b560b`
and its original runtime revision `e2ebfb06550fdcda0eb03590aecd9cf5e27a6dbc`.
Neither historical run is relabeled as evidence for this reconciliation.

External, model-dependent, latency, consolidation, and productivity numbers are not included in
this offline registry unless a redacted immutable artifact with the same three bindings exists. Use
the [public benchmark runbook](docs/PUBLIC_BENCHMARK_RUNBOOK.md) to produce registry evidence.
Expand All @@ -137,13 +174,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-pr260-nested-uri-redaction-runtime-20261018-e2ebfb06550f.json --output docs/images/context-efficiency-pr260-nested-uri-redaction-runtime-20261018-e2ebfb06550f.svg --png-output docs/images/context-efficiency-pr260-nested-uri-redaction-runtime-20261018-e2ebfb06550f.png
python scripts/render_benchmark_report.py --report docs/benchmark-evidence/offline-fixtures-pr270-guard-installer-20261020.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-pr260-nested-uri-redaction-runtime-20261018-e2ebfb06550f.json --output docs/images/evidence-backed-agent-examples-pr260-nested-uri-redaction-runtime-20261018-e2ebfb06550f.svg --png-output docs/images/evidence-backed-agent-examples-pr260-nested-uri-redaction-runtime-20261018-e2ebfb06550f.png
python -m scripts.render_benchmark_examples --report docs/benchmark-evidence/offline-fixtures-pr270-guard-installer-20261020.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 @@ -202,7 +239,9 @@ frontier-model QA score.
tokens (**54.71% 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 for the legacy candidate-page view. The registered
v9 artifact predates `packed_quality`, so no packed-quality aggregate is published from it.
v9 artifact predates `packed_quality` and retains no inferred packed-quality result.
The new artifact reports candidate and packed Recall@5, Hit@5, and answer-token recall
separately; all six aggregates are 1.000 on these 26 questions.
These aggregates are evidence ID
`offline-performance` in the registry above. `--filler-memories`, `--candidate-k`, and
`--retrieval-profile` make scaling and routing experiments executable, but their results need
Expand Down
Loading
Loading