You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+41-15Lines changed: 41 additions & 15 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -44,7 +44,7 @@ by default, or accept an explicit workspace plus optional `from_ts`, `to_ts`, an
44
44
`release_version` filters.
45
45
46
46
<palign="center">
47
-
<imgsrc="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%">
47
+
<imgsrc="https://raw.githubusercontent.com/Coding-Dev-Tools/engraphis/main/docs/images/context-efficiency.svg"alt="Dark chart of registered deterministic fixtures. Structure-aware chunks reduce retrieved 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 11,138 rather than 24,590 tokens. Retrieved-candidate quality is labeled separately from packed-context quality, both measured in the selected report with packed-quality fields. Actual MCP transport and provider billing are not measured."width="100%">
48
48
<br>
49
49
<sup>Less repeated history means more room for the task, tools, and useful evidence.</sup>
50
50
</p>
@@ -73,17 +73,27 @@ its counting boundary explicit.
73
73
|---|---|---|---|
74
74
| 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 |
75
75
| 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 |
76
-
| 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**|
76
+
| Full versus compact recall payload proxy across one 26-question pass within a 260-timed-recall CodeMem run | Full proxy: **24,590**`engraphis.regex.v1` tokens → compact proxy: **11,138** tokens |**13,452 proxy tokens avoided** (**54.71% lower**) | 26 payload samples; 260 timed recalls; Recall@5, hit@5, and answer-token recall all **1.000**|
77
77
| 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 |
78
78
79
-
These values are evidence IDs `offline-chunking` and `offline-performance` in
Benchmark-driven alternatives are opt-in: `packing_mode="coverage"` keeps complete evidence
564
+
units from more source memories, while `retrieval_recipe="conversation"` and
565
+
`retrieval_recipe="long_session"` select the measured depth/budget starting points. The
566
+
historical `legacy`/`default` settings remain unchanged. For a value that must survive a file
567
+
edit or tool call exactly, Smart and Classic `engraphis_remember` and the Python/service write
568
+
APIs accept source-bound `exact_value` plus its `exact_value_type`. MCP remember requires a
569
+
unique occurrence; Python/service writes can select a repeated occurrence with `exact_value_span`.
570
+
Packed binding metadata requires the complete memory source, preserving conditions in any
571
+
language. Boundary whitespace outside the bound value may be trimmed. Coverage withholds a
572
+
bound group that cannot fit; legacy keeps its selected text but omits the incomplete binding.
573
+
Corrections and content revisions clear the old binding when content changes;
574
+
pass `exact_value` to explicitly bind the replacement, with `exact_value_span=[start,end]`
575
+
for a repeated occurrence, or `clear_exact_value=true` to remove a binding. Unchanged content
576
+
and title-only revisions preserve valid bindings. History preserves the original record.
577
+
MCP response trimming removes binding metadata whenever its supporting context is omitted.
578
+
579
+
For bi-temporal reads, `valid_at` selects what was true at a Unix timestamp and `known_at` selects
554
580
what Engraphis had learned then. `as_of` remains a compatibility alias for `valid_at`; supplying
555
581
both is allowed only when they match.
556
582
@@ -762,7 +788,7 @@ file. It never searches the working directory for `.env`, and explicit process v
762
788
|---------|---------|-------------|
763
789
|`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. |
764
790
|`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. |
765
-
|`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). |
791
+
|`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). |
766
792
|`ENGRAPHIS_HOST`|`127.0.0.1`| Server bind address |
767
793
|`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 |
768
794
|`ENGRAPHIS_SERVICE_MODE`|`customer`| The public package supports only `customer`; hosted vendor, relay, compute, and worker roles are not distributed here |
0 commit comments