Skip to content

Commit dcb591d

Browse files
cdeustclaude
andcommitted
docs: restore the marketplace and green sections word for word
The fresh-context review of the previous head found that the sections the PR body described as restored verbatim were not. The green section had lost two hedges and its closing paragraph, and 23 lines overall; Security and Privacy Policy had been merged into one paraphrased block; Support and the License opener carried small wording changes. Every one of those blocks is now the v4.20.0 text, checked by a word-level comparison in the same script that spliced it: the whole Green software engineering section, the Verification section that follows it in v4.20.0 (the per-mechanism ablation evidence and both paper PDFs), Security, Privacy Policy, Support, License and Citation all compare identical to v4.20.0 after whitespace normalisation. The cross-platform positioning paragraph no longer carries its own host list, which the review found did not match the table it pointed to; it now names Claude Code, the Claude Desktop bundle and Claude Cowork and defers every other host to the table, which is the only place that enumerates them. The owner's tone pass (0571343) survives unchanged: the eleven lines that differ from it are the same moved, extended or absorbed lines as before. No heading is duplicated. Gates on this head: link resolution, check_doc_claims.py, check_version_surfaces.py (17 sites), and the codex-contract and version-surface tests. Co-Authored-By: Claude Fable 5.1 <[email protected]>
1 parent f20cb17 commit dcb591d

1 file changed

Lines changed: 78 additions & 59 deletions

File tree

‎README.md‎

Lines changed: 78 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -32,9 +32,10 @@ default, or PostgreSQL + pgvector if you prefer. No LLM in the retrieval loop, a
3232
leaves localhost unless you configure an integration that does. Your project's memory is a
3333
file you own and can delete.
3434

35-
**Cross-platform is how it is built.** One stdio MCP server, the same 52 tools on Claude Code,
36-
Claude Desktop, Claude Cowork, Codex, ChatGPT desktop, Gemini CLI, Cursor, Windsurf and VS
37-
Code. What differs per host is stated in a table below, not discovered after install.
35+
**Cross-platform is how it is built.** One stdio MCP server and the same 52 tools on Claude
36+
Code, in the Claude Desktop bundle, under Claude Cowork, and on every local stdio MCP host
37+
listed in the table below. What differs per host is stated there, not discovered after
38+
install.
3839

3940
**Eco-responsible is what we are aiming at.** Work that never reaches a datacenter is work
4041
nobody has to power, and an agent that finds the right context first time re-reads fewer
@@ -286,46 +287,50 @@ deliberately does not claim are in [docs/codex-plugin.md](docs/codex-plugin.md).
286287

287288
## Green software engineering
288289

289-
Cortex runs a standing efficiency programme, gated by the same evidence rule as the retrieval
290-
work: **no unsourced efficiency claim ships.** Waste is treated as a defect with a
291-
reproduction, not as a virtue to advertise.
292-
293-
### The measurement harness, and what it does not establish
294-
295-
`benchmarks/energy/` implements the
296-
[Green Software Foundation SCI specification](https://sci.greensoftware.foundation/):
297-
operational emissions `O = E × I`, embodied allocation `M = TE × TS × RS`, reported per
298-
functional unit. For the embedding path the functional unit is **1000 model input tokens**,
299-
counted from the tokenizer's own `attention_mask`, never estimated from characters.
300-
301-
Read [benchmarks/energy/README.md](benchmarks/energy/README.md) before quoting anything from
302-
it. Its first paragraph is the important one: the automated fixtures exercise arithmetic and
303-
failure paths, they **do not measure device energy and do not establish an energy
304-
improvement.** By design:
305-
306-
- **No default carbon factors.** `--carbon-intensity` (gCO2eq/kWh) and `--embodied`
307-
(gCO2eq/s, an already allocated rate) are mandatory operator inputs, validated before any
308-
model import. The harness records the values and their units; it does not vouch for their
309-
provenance.
310-
- **A stated boundary.** `raw_system_energy_j` is the sensor's combined CPU+GPU+ANE estimate.
311-
It is neither wall-plug energy nor a complete device SCI score: memory, storage, screen,
312-
power-supply losses, model warm-up and token counting are all excluded.
313-
- **Artifacts or it did not happen.** A successful run preserves `results.json`, a
314-
`MANIFEST.json` of commit and source hashes, and the exact analyzed `powermetrics.txt`
315-
snapshot.
316-
317-
No energy results are committed to this repository. A figure measured on one operator's
318-
machine, region and duty cycle is not a property of the software, and publishing it as one
319-
would be the drift this programme exists to prevent.
290+
Cortex runs a standing efficiency programme, gated by the same evidence rule as
291+
the retrieval work: **no unsourced efficiency claim ships.** Waste is treated as
292+
a defect with a reproduction, not as a virtue to advertise.
293+
294+
### The measurement harness — and what it does not establish
295+
296+
`benchmarks/energy/` implements the [Green Software Foundation SCI
297+
specification](https://sci.greensoftware.foundation/): operational emissions
298+
`O = E × I`, embodied allocation `M = TE × TS × RS`, reported per functional
299+
unit. For the embedding path the functional unit is **1000 model input tokens**,
300+
counted from the tokenizer's own `attention_mask` — never estimated from
301+
characters.
302+
303+
Read `benchmarks/energy/README.md` before quoting anything from it. Its own
304+
first paragraph is the important one: the automated fixtures exercise arithmetic
305+
and failure paths, they **do not measure device energy and do not establish an
306+
energy improvement.** Further, by design:
307+
308+
- **No default carbon factors.** `--carbon-intensity` (gCO2eq/kWh) and
309+
`--embodied` (gCO2eq/s, an *already allocated* rate) are mandatory operator
310+
inputs, validated before any model import. The harness records the values and
311+
their units; it does not vouch for their provenance. You supply the region,
312+
observation period, lifecycle assessment and reservation assumptions.
313+
- **A stated boundary.** `raw_system_energy_j` is the sensor's combined
314+
CPU+GPU+ANE estimate. It is neither wall-plug energy nor a complete device SCI
315+
score: memory, storage, screen, power-supply losses, model warm-up and token
316+
counting are all excluded.
317+
- **Artifacts or it did not happen.** A successful run preserves `results.json`,
318+
a `MANIFEST.json` of commit and source hashes, and the exact analyzed
319+
`powermetrics.txt` snapshot.
320+
321+
No energy results are committed to this repository. That is deliberate: a
322+
figure measured on one operator's machine, region and duty cycle is not a
323+
property of the software, and publishing it as one would be the drift this
324+
programme exists to prevent.
320325

321326
### What has actually shipped
322327

323-
Efficiency work lands as ordinary reviewed PRs.
328+
Efficiency work lands as ordinary reviewed PRs. Two workstreams are merged:
324329

325330
| Workstream | Change | PR |
326331
|---|---|---|
327332
| **CI / build** | run pytest once, on the coverage leg, instead of twice | [#475](https://github.com/cdeust/Cortex/pull/475) |
328-
| | build runtime images only on Docker changes, plus a weekly validation | [#476](https://github.com/cdeust/Cortex/pull/476) |
333+
| | build runtime images only on Docker changes + a weekly validation | [#476](https://github.com/cdeust/Cortex/pull/476) |
329334
| | cache pinned dependency and actionlint downloads | [#477](https://github.com/cdeust/Cortex/pull/477) |
330335
| | sdist under 5 MB, with a byte-identical wheel | [#478](https://github.com/cdeust/Cortex/pull/478) |
331336
| | measured job timeouts; cancel superseded PR runs | [#479](https://github.com/cdeust/Cortex/pull/479) |
@@ -336,21 +341,40 @@ Efficiency work lands as ordinary reviewed PRs.
336341
| | audit and clean orphan plugin dependencies | [#484](https://github.com/cdeust/Cortex/pull/484) |
337342
| | rotate telemetry and detached-worker logs | [#485](https://github.com/cdeust/Cortex/pull/485) |
338343
| | persist hook cascade cadence; cool down misses | [#486](https://github.com/cdeust/Cortex/pull/486) |
339-
| | pinned CPU-only Torch on Linux, no CUDA payload pulled | [#487](https://github.com/cdeust/Cortex/pull/487) |
344+
| | pinned CPU-only Torch on Linux — no CUDA payload pulled | [#487](https://github.com/cdeust/Cortex/pull/487) |
340345

341-
The hook work is the load-bearing one, because hooks run on every tool event. Deferring the
342-
handler/store stack keeps hook boot at **~0.05 s** against **~0.6 s** for the full registry
343-
import (measured 2026-07-28; the constant is cited in `mcp_server/hooks/auto_recall.py` at its
344-
call sites, per the no-invented-constants rule).
346+
The hook work is the load-bearing one, because hooks run on *every* tool event.
347+
Deferring the handler/store stack keeps hook boot at **~0.05 s** against
348+
**~0.6 s** for the full registry import (measured 2026-07-28; the constant is
349+
cited in `mcp_server/hooks/auto_recall.py` at its call sites, per the
350+
no-invented-constants rule).
345351

346352
### Demand reduction is the primary lever
347353

348-
The largest efficiency term in an LLM-assisted workflow is not this server's own CPU. It is
349-
the tokens a model must process because the right context was not found the first time. That
350-
makes retrieval quality an energy property, and it is why the benchmark table above and this
351-
section are the same programme: `response_budget.py` bounds a payload and keeps ids so
352-
truncation stays resumable, the reranker degrades to first-stage scores rather than fetching
353-
a model, and `CORTEX_RERANKER_OFFLINE=1` refuses the download outright.
354+
The largest efficiency term in an LLM-assisted workflow is not this server's own
355+
CPU — it is the tokens a model must process because the right context was not
356+
found the first time. That makes retrieval quality an energy property, and it is
357+
why the benchmark tables above and this section are the same programme:
358+
`response_budget.py` bounds a payload and keeps ids so truncation stays
359+
resumable, the reranker degrades to first-stage scores rather than fetching a
360+
model, and `CORTEX_RERANKER_OFFLINE=1` refuses the download outright.
361+
362+
This paragraph is a design rationale, not a measurement. Cortex publishes no
363+
token-savings or CO2 figure for end-to-end agent sessions, because it has not
364+
measured one.
365+
366+
---
367+
368+
## Verification
369+
370+
Every benchmark headline above is backed by a per-mechanism ablation campaign — full *n*, single-seed, with code SHAs, dirty flags, manifests, and per-row JSON preserved:
371+
372+
- **LongMemEval-S, 17 rows, n=500** — `docs/benchmarks/e1-v3-results.md`. Per-mechanism deltas at the calibrated equilibrium + category-specialization analysis.
373+
- **LoCoMo, 14 rows, n=1986** — `docs/benchmarks/e1-v3-locomo-results.md` (pre-fix) and `docs/benchmarks/e1-v3-locomo-results-post-fix.md` (post plasticity result-shape fix). Two-baseline design (NO_CONSOLIDATION / WITH_CONSOLIDATION).
374+
375+
The full per-mechanism evidence lives in the thermodynamic paper (§6.3); the BEAM decay dose-response (§6.4) documents a re-scoped negative result after a dirty-store confound was caught and traced. **[Thermodynamic Memory vs. Flat-Importance Stores (PDF, 34 pages)](docs/arxiv-thermodynamic/main.pdf)** · **[Stage-Aware Context Assembly (PDF, 39 pages)](docs/arxiv-context-assembly/main.pdf)**.
376+
377+
---
354378

355379
## Under the hood
356380

@@ -378,22 +402,17 @@ Clean Architecture, concentric layers: `server → handlers → core ← shared`
378402
PostgreSQL and OTLP telemetry add network activity only when explicitly configured; see
379403
[PRIVACY.md](PRIVACY.md).
380404

405+
## Security
406+
407+
Runs **100% locally** — MCP over stdio, the storage backend (SQLite file or PostgreSQL on localhost) never leaves your machine (the optional [hypermnesia-mcp-viz](https://github.com/cdeust/cortex-viz) companion binds its server to 127.0.0.1). No data leaves your machine. SafeSkill scan: **94/100** (code 97, content 88 — [docs/safeskill-report.json](docs/safeskill-report.json)).
408+
381409
## Privacy Policy
382410

383-
Cortex is **local-first**: your memories, conversations and profiles stay on your machine,
384-
stored in a local SQLite database (`~/.claude/methodology/memory.db`) by default, or in a
385-
PostgreSQL database you control. Cortex sends **no** memories, content or telemetry to the
386-
author, to Anthropic, or to any third party. The only outbound network activity is a one-time
387-
download of open-source embedding and reranking models from Hugging Face (model files only),
388-
plus any integrations you explicitly configure. The optional
389-
[hypermnesia-mcp-viz](https://github.com/cdeust/cortex-viz) companion binds its server to
390-
127.0.0.1. SafeSkill scan: **94/100** (code 97, content 88,
391-
[docs/safeskill-report.json](docs/safeskill-report.json)). Full policy:
392-
**[PRIVACY.md](PRIVACY.md)**.
411+
Cortex is **local-first**: your memories, conversations, and profiles stay on your machine — stored in a local SQLite database (`~/.claude/methodology/memory.db`) by default, or in a PostgreSQL database you control. Cortex sends **no** memories, content, or telemetry to the author, Anthropic, or any third party. The only outbound network activity is a one-time download of open-source embedding/reranking models from Hugging Face (model files only), plus any integrations you explicitly configure. Full policy: **[PRIVACY.md](PRIVACY.md)**.
393412

394413
## Support
395414

396-
- **Issues and bug reports:** [GitHub Issues](https://github.com/cdeust/Cortex/issues)
415+
- **Issues & bug reports:** [GitHub Issues](https://github.com/cdeust/Cortex/issues)
397416
- **Security disclosures:** see [SECURITY.md](SECURITY.md)
398417
- **Contact:** [[email protected]](mailto:[email protected])
399418

@@ -414,7 +433,7 @@ python scripts/check_craftsmanship.py # file and method caps, layer whitelist, s
414433

415434
## License
416435

417-
MIT, see [LICENSE](LICENSE).
436+
MIT — see [LICENSE](LICENSE).
418437

419438
This software is the independent work of Clément Deust. It was developed outside any
420439
employment relationship and is not affiliated with, endorsed by, or owned by any past or

0 commit comments

Comments
 (0)