Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust

docs(query): record draft context-budget measurements and limits

Mihael Zamin Sousa715fa746f480
diff --git a/docs/benchmarks/README.md b/docs/benchmarks/README.md
index 992bd6e2..d4ec2b12 100644
--- a/docs/benchmarks/README.md
+++ b/docs/benchmarks/README.md
@@ -251,3 +251,9 @@ sustained on a 282-question prefix); the local-embeddings run is bounded
by the embedder at roughly 19 pages/s and lands near half an hour. Expect
about ±15% of run-to-run spread on wall clock when the machine has other
work on it; accuracy noise is the ±0.005 band above, not wall clock.
+
+## Local builder measurements
+
+[Draft query-answer context admission](query-answer-context-draft.md) records
+synthetic prompt sizes and local debug timings for #1684. It does not measure
+retrieval quality, answer accuracy or provider token usage.
diff --git a/docs/benchmarks/query-answer-context-draft.csv b/docs/benchmarks/query-answer-context-draft.csv
new file mode 100644
index 00000000..e6a3adc2
--- /dev/null
+++ b/docs/benchmarks/query-answer-context-draft.csv
@@ -0,0 +1,65 @@
+fixture,hits,mode,request_built,content_bytes,content_scalars,admitted,omitted,clipped,estimated_input_tokens,reserved_output_tokens,p50_ns,p95_ns
+ascii-short,1,disabled,true,838,836,1,0,0,NA,2000,5317,6378
+ascii-short,1,16000,true,942,940,1,0,0,2749,2000,49540,76420
+ascii-long,1,disabled,true,160806,160804,1,0,0,NA,2000,5886,7110
+ascii-long,1,16000,false,0,0,0,1,0,162388,2000,30645,33244
+ascii-short,10,disabled,true,3611,3609,10,0,0,NA,2000,25742,28527
+ascii-short,10,16000,true,3905,3903,10,0,0,5712,2000,57676,64837
+ascii-long,10,disabled,true,163579,163577,10,0,0,NA,2000,28811,37699
+ascii-long,10,16000,false,0,0,0,10,0,162389,2000,34859,41016
+ascii-short,50,disabled,true,15971,15969,50,0,0,NA,2000,128594,143027
+ascii-short,50,16000,true,12156,12154,35,15,0,13963,2000,161532,262730
+ascii-long,50,disabled,true,175939,175937,50,0,0,NA,2000,135831,243251
+ascii-long,50,16000,false,0,0,0,50,0,162389,2000,56977,64067
+ascii-short,100,disabled,true,31422,31420,100,0,0,NA,2000,261368,270362
+ascii-short,100,16000,true,12156,12154,35,65,0,13963,2000,185125,200179
+ascii-long,100,disabled,true,191390,191388,100,0,0,NA,2000,260940,279293
+ascii-long,100,16000,false,0,0,0,100,0,162390,2000,87137,99238
+pt-BR-short,1,disabled,true,853,836,1,0,0,NA,2000,2907,6382
+pt-BR-short,1,16000,true,957,940,1,0,0,2764,2000,27524,32205
+pt-BR-long,1,disabled,true,160821,160804,1,0,0,NA,2000,6029,9667
+pt-BR-long,1,16000,false,0,0,0,1,0,162388,2000,30077,39652
+pt-BR-short,10,disabled,true,3761,3609,10,0,0,NA,2000,27072,46636
+pt-BR-short,10,16000,true,4055,3903,10,0,0,5862,2000,58333,59214
+pt-BR-long,10,disabled,true,163729,163577,10,0,0,NA,2000,29925,36505
+pt-BR-long,10,16000,false,0,0,0,10,0,162389,2000,35279,36807
+pt-BR-short,50,disabled,true,16721,15969,50,0,0,NA,2000,134011,417258
+pt-BR-short,50,16000,true,12193,11687,34,16,1,14000,2000,160079,485288
+pt-BR-long,50,disabled,true,176689,175937,50,0,0,NA,2000,134825,148162
+pt-BR-long,50,16000,false,0,0,0,50,0,162389,2000,57143,65304
+pt-BR-short,100,disabled,true,32922,31420,100,0,0,NA,2000,270657,291941
+pt-BR-short,100,16000,true,12191,11685,34,66,1,13998,2000,194156,228801
+pt-BR-long,100,disabled,true,192890,191388,100,0,0,NA,2000,285287,490144
+pt-BR-long,100,16000,false,0,0,0,100,0,162390,2000,89183,127853
+CJK-short,1,disabled,true,1318,836,1,0,0,NA,2000,5778,6612
+CJK-short,1,16000,true,1422,940,1,0,0,3229,2000,30687,38724
+CJK-long,1,disabled,true,161286,160804,1,0,0,NA,2000,8982,13487
+CJK-long,1,16000,false,0,0,0,1,0,162388,2000,33614,38390
+CJK-short,10,disabled,true,8411,3609,10,0,0,NA,2000,56439,64477
+CJK-short,10,16000,true,8705,3903,10,0,0,10512,2000,88177,97836
+CJK-long,10,disabled,true,168379,163577,10,0,0,NA,2000,59459,70213
+CJK-long,10,16000,false,0,0,0,10,0,162389,2000,39113,52858
+CJK-short,50,disabled,true,39971,15969,50,0,0,NA,2000,293947,538540
+CJK-short,50,16000,true,12192,5366,15,35,1,13999,2000,143189,168027
+CJK-long,50,disabled,true,199939,175937,50,0,0,NA,2000,543540,548007
+CJK-long,50,16000,false,0,0,0,50,0,162389,2000,97223,99672
+CJK-short,100,disabled,true,79422,31420,100,0,0,NA,2000,728712,1087616
+CJK-short,100,16000,true,12189,5365,15,85,1,13996,2000,179161,195911
+CJK-long,100,disabled,true,239390,191388,100,0,0,NA,2000,849484,1302720
+CJK-long,100,16000,false,0,0,0,100,0,162390,2000,94277,120358
+code-short,1,disabled,true,838,836,1,0,0,NA,2000,2819,6912
+code-short,1,16000,true,942,940,1,0,0,2749,2000,48517,51981
+code-long,1,disabled,true,160806,160804,1,0,0,NA,2000,9190,10430
+code-long,1,16000,false,0,0,0,1,0,162388,2000,52679,55807
+code-short,10,disabled,true,3611,3609,10,0,0,NA,2000,48854,50481
+code-short,10,16000,true,3905,3903,10,0,0,5712,2000,62866,123146
+code-long,10,disabled,true,163579,163577,10,0,0,NA,2000,46231,121773
+code-long,10,16000,false,0,0,0,10,0,162389,2000,59883,63455
+code-short,50,disabled,true,15971,15969,50,0,0,NA,2000,237090,242912
+code-short,50,16000,true,12156,12154,35,15,0,13963,2000,266812,276483
+code-long,50,disabled,true,175939,175937,50,0,0,NA,2000,150269,423908
+code-long,50,16000,false,0,0,0,50,0,162389,2000,89577,98298
+code-short,100,disabled,true,31422,31420,100,0,0,NA,2000,250469,491151
+code-short,100,16000,true,12156,12154,35,65,0,13963,2000,179760,276061
+code-long,100,disabled,true,191390,191388,100,0,0,NA,2000,469440,489438
+code-long,100,16000,false,0,0,0,100,0,162390,2000,85888,95510
diff --git a/docs/benchmarks/query-answer-context-draft.md b/docs/benchmarks/query-answer-context-draft.md
new file mode 100644
index 00000000..254c8310
--- /dev/null
+++ b/docs/benchmarks/query-answer-context-draft.md
@@ -0,0 +1,71 @@
+# Query-answer context admission: draft local measurements
+
+This receipt accompanies the default-disabled proposal in #1684. Its configuration,
+response contract and pruning policy still need maintainer agreement. It measures
+builder size and local execution time, not answer correctness or provider usage.
+
+## Provenance
+
+- Feature base: `e7e17555efb6a95596480249598ad517ff587310`.
+- Citation-validation prerequisite: `91aa3d26df4df8064b270f8d5242cfca465d08d7`.
+- Candidate code: `71f9cd36015ab4a578641630714615e5b37f4768`.
+- Run: 2026-10-25 UTC, Linux 6.18.55 x86_64, AMD EPYC 9V74, 9 visible logical CPUs.
+- Rust: `1.95.0 (59807616e 2026-04-14)`, debug test profile, `CARGO_INCREMENTAL=0`.
+- Provider/model: none. No model requests or paid evaluations.
+- Fixture: `server::tests::answer_budget_measurements`; SHA-256 of that function's
+ source through the following helper boundary:
+ `570d36eca47aaf411461991588642fbc432124ed6800bd99c1f1fe1d81bbd6e7`.
+- CSV SHA-256: `83d1ead149d3fe2c0108135ca6440fd8b29db39b872453cab918b66da4c787ed`.
+- Published candidate tree equals local tested commit `bd3179ef5d89ebdc5bd71167425d821d0c6e9f5e`
+ (tree `ac2c5787080eab464d7958a09ccc0c1733c64f41`).
+- Both modes ran in the candidate binary. Disabled admission delegates to the
+ unchanged baseline builder; this is a mode comparison, not two separately
+ compiled binaries. The disabled-request regression test compares their fields.
+
+The fixture uses 1, 10, 50 and 100 hits, each with a 240-scalar snippet, across
+ASCII, pt-BR, CJK and code. Questions are either 32 bytes or 160,000 bytes. Each
+mode uses 20 warmup calls and 31 timed trials of 20 calls. The CSV records per-call
+p50 and p95 nanoseconds from those trials. Other builds ran on the shared host,
+so these debug timings are exploratory and do not establish production latency.
+
+## Results
+
+The table shows the 100-hit short-question cases. Content bytes count only system
+and user messages. The enabled mode also counts serialized schema bytes and 1024
+envelope units, then reserves 2000 output tokens, within its 16000-unit target.
+The one-byte-per-estimated-input-token contract is not a tokenizer guarantee.
+
+| Fixture | Disabled bytes | Enabled bytes | Byte reduction | Admitted / omitted / clipped | Disabled p50 / p95 µs | Enabled p50 / p95 µs |
+|---|---:|---:|---:|---|---:|---:|
+| ascii | 31422 | 12156 | 61.31% | 35 / 65 / 0 | 261.37 / 270.36 | 185.12 / 200.18 |
+| pt-BR | 32922 | 12191 | 62.97% | 34 / 66 / 1 | 270.66 / 291.94 | 194.16 / 228.80 |
+| CJK | 79422 | 12189 | 84.65% | 15 / 85 / 1 | 728.71 / 1087.62 | 179.16 / 195.91 |
+| code | 31422 | 12156 | 61.31% | 35 / 65 / 0 | 250.47 / 491.15 | 179.76 / 276.06 |
+
+All long-question cases produced no request in the enabled mode. Their receipt
+can report estimated input above the limit: it explains the refused request,
+not a prompt sent to a provider. CSV `NA` means disabled mode has no input-token
+estimate; it does not mean zero tokens. `content_bytes=0` with `request_built=false`
+means no request was built.
+
+The one-hit ASCII case added local work: p50 rose from 5.317 µs to 49.540 µs,
+including schema sizing. Larger cases did less rendering because they omitted
+sources. No overhead acceptance threshold has been agreed.
+
+The CJK case admits only 15 of 100 sources at this conservative budget. Clipping
+can remove a correction or qualification. Deterministic tests check that supplied
+corrections remain intact when they fit and that superseded status is labelled;
+answer accuracy under pruning remains unmeasured and blocks a ready-for-review
+claim. Retrieval hits and ranking remain unchanged.
+
+Full measurements: [CSV](query-answer-context-draft.csv).
+
+## Reproduce
+
+```sh
+cargo test -p ai-memory-mcp --lib answer_budget_measurements -- --ignored --nocapture
+```
+
+Lines beginning `C2CSV,` contain the receipt. Remove that prefix to recover the
+CSV. No provider configuration is needed. The test is ignored in normal CI so
+its timing loop does not become part of the everyday test run.