Repository navigation
docs: rewrite the README around its three positions, marketplace-complete - #548
Merged
Merged
Conversation
777 lines down to 180. The old one buried what a reader decides on under a release archive that stopped at v4.13.0, twelve releases behind, and a badge whose alt text said 4.17.1 while the badge itself said 4.20.0. The rewrite keeps what a reader needs to decide and to install: the problem, the install, what is automatic versus what you call, one benchmark table with its provenance, the storage trade-off as a table rather than three paragraphs, and the limits stated before the reader hits them. The cortex-viz identity migration is preserved in full, folded into a details block, because two contract tests pin those exact commands and they are right to. Every link in the file was resolved against the tree; two I first wrote did not exist and were replaced with real targets. The systemic half: the badge SVG is generated and gated but its README alt text is hand-written prose that nothing read, which is how it drifted three minor versions. It is now the 17th version surface, and a test drives the desync rather than asserting the count alone. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
The first cut compressed the old sections instead of deciding what the file should say. It kept the generic claim (stores what happened, brings it back, which is what every memory tool claims) and deleted the two parts that made the case: the concrete Monday/Thursday scenario and the real tool output. What differentiates Cortex is quality control on memory, and none of it was above the fold. The predictive-coding gate that merges a near-duplicate instead of filing it beside the original. Provenance grading at write time, locally: a memory whose file path no longer resolves is stored as unverifiable rather than returned later as fact. Supersession, so a correction demotes what it replaces and the chain stays readable. Thermodynamic decay, so the store curates itself. The file now opens on the problem those solve (a store that accumulates gets worse as it grows and you cannot tell what to trust), shows each mechanism with output taken from a real run, and only then explains what it feels like to use. The scenario is restored, tightened. 229 lines, from 777. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
cdeust
commented
Sep 9, 2026
cdeust
left a comment
cdeust
left a comment
Owner
Author
There was a problem hiding this comment.
Reviewed the version-badge gate and README against the repository’s privacy policy, benchmark artifact and migration contracts. No blocking finding remains in this reviewed scope.
Follow-up commit 05713431 updates only README.md:
- Leads with practical benefits and one installation section; explains terminology and labels the workflow as illustrative.
- Makes the benchmark’s historical v4.14.1 origin, single run and disabled consolidation explicit, with direct artifact and code links. It does not present those figures as v4.20.0 performance or answer accuracy.
- Corrects the single-network-call claim: both models download, and configured integrations, remote PostgreSQL and opt-in telemetry can use the network.
- Explains that verified references are not proof of a claim’s truth. Preserves storage differences, host limitations and the complete migration block.
Validation: 25 version-surface tests passed; version and document-claim gates passed; both existing README migration contract checks passed; all 23 local Markdown/HTML links resolved; migration block byte-for-byte unchanged; Ruff check and format passed; git diff --check passed. Runtime code and tests are unchanged by this follow-up. No benchmark rerun or fresh release-performance claim is implied.
This is an AI-assisted code/documentation review, posted as a comment rather than an independent human approval. CI must validate the new head before merge.
cdeust
changed the title
…coming pass Base is 0571343, the owner's tone pass, kept verbatim: install first, the hedged wording on consolidation and grading, the illustrative example in place of internal ids, and the benchmark table labelled as a historical v4.14.1 run. Nothing from that pass is rewritten; the merge adds to it. Added, because the marketplace and the MCPB directory require them and both earlier cuts in this PR had dropped them: the not-an-Anthropic- product affiliation disclaimer under the banner, Privacy Policy and Support sections matching the privacy_policies and support fields manifest.json already declares, the License section with its independent-work statement and algorithm attribution, and the Citation block. All restored from the pre-rewrite README, word for word. Added, for the three positions the project holds: the Sovereign / Cross-platform / Eco-responsible block after the header, the full what-works-where host matrix with the uvx, Gemini extension and Codex launch commands, and the Green software engineering section with every hedge intact (no CO2 or energy figure is published; the SCI tooling's own README says what it does not establish; the shipped efficiency PRs are listed; the hook-boot constant is cited to auto_recall.py). The one paragraph that moved rather than stayed put is the never-downgraded PostgreSQL note, from Storage into Install, where the behaviour it describes happens. The Project link row is absorbed into Development. 464 lines. Every relative link resolves against the tree. The codex contract tests and the version-surface tests pass unchanged. Co-Authored-By: Claude Fable 5.1 <[email protected]>
5 of 6 tasks
cdeust
added a commit
that referenced
this pull request
Sep 9, 2026
….0 (#549) Follow-up to #548, cut from main at 5e94667. README.md only. A fresh-context review of the merged head found that the blocks the PR had described as restored from v4.20.0 were not. The Green software engineering section had lost 23 lines, including two hedges that are the point of the section: that the operator supplies the region, observation period, lifecycle assessment and reservation assumptions, and the closing paragraph stating that no token-savings or CO2 figure is published for end-to-end sessions because none has been measured. Security had been folded into Privacy Policy and both paraphrased; Support and the License opener carried small wording changes. Every one of those blocks is now the v4.20.0 text, plus the Verification section that follows the green section there (the per-mechanism ablation evidence and both paper PDFs), which had been dropped in an earlier cut. Each block was compared to `git show v4.20.0:README.md` at word level after whitespace normalisation inside the splicing script; all comparisons print True. The cross-platform positioning paragraph no longer lists hosts on its own, since that list did not match the table it pointed to; it names Claude Code, the Claude Desktop bundle and Claude Cowork and defers every other host to the table. Deliberately not reintroduced: the independent-project disclaimer the owner removed on main in 5e94667. Gates on this head: link and cited-path resolution, no duplicated heading, check_doc_claims.py, check_version_surfaces.py (17 sites), and the codex-contract and version-surface tests (33 pass). Co-authored-by: Claude Fable 5.1 <[email protected]>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Four passes are on this branch. The first two removed content the Anthropic marketplace and the MCPB directory require, and the owner's verdict on them stands. The third layered the missing sections and the project's three positions onto the owner's own tone pass (0571343). A fresh-context review of that head found the sections described as "verbatim" were not; the fourth pass makes them so, checked mechanically.
Base: the owner's pass, verbatim
Install first. Hedged wording where the mechanism does not guarantee an outcome. An illustrative example instead of internal memory ids. The benchmark table labelled as a historical v4.14.1 run. None of that is rewritten; the eleven lines that differ from 0571343 are moved, extended or absorbed, and are listed in the third commit.
Restored word for word from v4.20.0
Checked by a word-level comparison inside the script that spliced them, all identical after whitespace normalisation: the affiliation disclaimer under the banner, the whole Green software engineering section including every hedge and its closing rationale paragraph, the Verification section that follows it in v4.20.0 (the per-mechanism ablation evidence and both paper PDFs), Security, Privacy Policy, Support, License with its independent-work statement and algorithm attribution, and Citation.
These are the sections
manifest.jsonimplies through itsprivacy_policies,supportandauthorfields, plus the ones the project's own evidence rules require.Added, for the three positions
A short block after the disclaimer names the three positions in the owner's framing: sovereign and accountable, cross-platform, eco-responsible. The cross-platform paragraph names Claude Code, the Claude Desktop bundle and Claude Cowork and defers every other host to the "Every other MCP host" table, which is the only place that enumerates them; the review found the earlier duplicated list did not match the table.
The what-works-where host matrix is restored as its own section with the
uvx, Gemini extension, Codex plugin and direct-fallback launch commands.What is gone
The "What's new" archive that stopped at v4.13.0. CHANGELOG.md carries the full history.
483 lines, from 777.
The version-surface gate
Unchanged since the first commit: the README badge alt text that had drifted to 4.17.1 while the SVG said 4.20.0 is the 17th version surface in
scripts/check_version_surfaces.py, with a test that drives the desync.Type of change
Test plan
Every relative link resolves against the working tree; the five code-formatted paths in the restored Verification section also exist.
git diff 05713431 -- README.md: 255 insertions, 11 deletions, each deletion accounted for.tests_py/scripts/test_codex_plugin_contract.pyandtest_version_surfaces.py: 33 pass. The two contract tests pinning the cortex-viz migration commands and theai-architect-mcp-specmention were not touched.scripts/check_doc_claims.pyandscripts/check_version_surfaces.py(17 sites): green.No duplicated H2 heading.
All existing tests pass.
New tests added for new behavior (
test_readme_badge_alt_desync_is_reported).Manual verification: link resolution, word-level identity of the restored blocks, heading uniqueness.
Audit notes
Two fresh-context reviews ran on this branch. The first, on f20cb17, returned REQUEST-CHANGES with two blockers (green section hedges dropped; Privacy Policy paraphrased and merged with Security), one should-fix (host list mismatch) and one nit (License opener). All four are closed in the fourth commit. A second pass on the current head is requested before merge.
The retrieval numbers keep their v4.14.1 provenance because no v4.20.0 run exists; the owner's historical-run labelling is kept.
Reviewer checklist
manifest.jsonalready declares).🤖 Generated with Claude Code