Repository navigation
docs(readme): lead with what Cortex does, in plain words - #509
Merged
Merged
Conversation
A visitor looking for a memory MCP for Claude Code met, in order: a
banner, eight badges, a paragraph opening on "36 cited brain
mechanisms", a nav bar, the entire four-product stack, and an
independence disclaimer — before a single line telling them what this
does for them. The promise arrived fifth, behind jargon and a catalogue.
- The tagline now leads with the outcome ("Give your AI coding agent a
memory that survives the session") and states the three things a
shopper checks immediately: runs locally, one click, no account.
- The seven-line stack block at the top duplicated the "The rest of the
stack" section that already exists further down. Collapsed to one line
plus a link, so it stops standing between the reader and the promise.
- Added a "What you get" list in plain language, and named the position
explicitly: sovereign memory, eco-responsible by intent. Sovereignty
is stated as a present fact (local file, 22 MB model, no LLM in the
retrieval loop, nothing leaving localhost); eco-responsibility is
stated as an intent held to the GSF SCI method, with an explicit "we
publish no CO2 or energy figure, because we have not measured one".
No claim is new: the 22 MB all-MiniLM-L6-v2 model, the SQLite default,
the 52 tools, the /why receipt command and MIT were each verified at
their source before being restated, and the pre-existing "9 lifecycle
hooks" figure was re-counted from .claude-plugin/plugin.json (9 entries
across 6 events) rather than carried over on trust.
check_doc_claims.py exits 0.
…ount The collapsed stack line said "four-piece stack", flattening three MCP servers that each keep evolving (memory, code graph, spec verification) together with the visualization and reasoning-agent companions, which are a different kind of thing. The full comparison further down is unchanged and still lists everything.
cdeust
marked this pull request as ready for review
September 8, 2026 14:27
This was referenced Sep 8, 2026
pull Bot
pushed a commit
to asleekgeek/Cortex
that referenced
this pull request
Sep 8, 2026
main went red on 089361a: tests_py/scripts/test_codex_plugin_contract.py ::test_current_companion_docs_use_canonical_publication_identities failed across Test (3.10/3.11/3.12/3.13) and Test (SQLite backend). 7663 passed, this one failed. My own defect, from cdeust#509. Collapsing the seven-line four-piece-stack block at the top of the README dropped the anchor <a href="https://github.com/cdeust/cortex-viz">hypermnesia-mcp-viz</a> which that test asserts on. The assertion is not decorative: the repo is named cortex-viz while the published plugin identity is hypermnesia-mcp-viz, and the test is the mechanical guard that the README keeps naming the canonical published identity rather than the repo slug. The replacement line said "visualization and reasoning-agent companions" in prose, naming neither. The fix names both companions with their links instead of alluding to them, which satisfies the contract and reads better than the vague form it replaces. Reproduced before fixing: the test fails on origin/main and passes after, 8 passed in that file. check_doc_claims.py and check_version_surfaces.py both clean. Note for a follow-up, not fixed here: this reached main because the CI `changes` filter excludes '*.md' from `code`, so a README-only PR skips every test job — yet this test's input IS README.md. The guard is gated off exactly when its subject changes. Filed separately rather than widening this fix.
pull Bot
pushed a commit
to asleekgeek/Cortex
that referenced
this pull request
Sep 8, 2026
Root cause of the cdeust#509 -> cdeust#510 incident. The `changes` filter classifies '*.md' out of `code`: code: - '**' - '!{*.md,docs/**/*.md,...}' so a README-only PR sets code=false and every test job is skipped. But part of that suite takes documentation as its INPUT: tests_py/scripts/test_codex_plugin_contract.py reads README.md and asserts on the canonical published identities (the hypermnesia-mcp-viz anchor, the viz/spec migration strings). The guards were therefore switched OFF exactly when their subject changed. cdeust#509 was a README-only diff, every test job skipped, it merged green, and the push to main went red on that test across five jobs (run 34238410970 — 7663 passed, 1 failed). cdeust#510 fixed the symptom; this fixes the reason it could reach main at all. Adds `docs` to test-sqlite's predicate only, not to the 3.10-3.13 matrix: test-sqlite already runs THE FULL SUITE in one ~5-minute job, so it covers the doc-contract tests at the smallest cost that closes the gap. Waking the whole matrix on every prose edit would undo cdeust#475-cdeust#481. scripts/check_ci_gate_results.py mirrors ci.yml's predicates — its own check_policy docstring requires the workflow and the executable policy to stay "in exact agreement". Changing only the workflow would have left two sources of truth disagreeing about when test-sqlite may skip, so _required_jobs gains the same condition and both files carry the same note. Caught by re-reading the diff, not by CI. Its two docs-only tests are updated to the new policy, and the first is turned into a named regression test that asserts skipping test-sqlite on a docs-only PR is NOT justified — the exact hole cdeust#509 fell through. Verified: actionlint 1.7.12 (the pinned version) clean on ci.yml; check_ci_gate_complete.py OK; both gate test files 38 passed, 159 subtests; craftsmanship, ruff check, ruff format, doc-claims all clean. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01StMBvNd7eVJGtpnC2zNsx1
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
2 participants
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.
The problem
Someone looking for a memory MCP to install in Claude Code lands here and meets, in this order: a banner, eight badges, a paragraph opening on "36 cited brain mechanisms", a nav bar, the entire four-product stack, an independence disclaimer — and only then a line telling them what this does for them.
The promise arrives fifth, behind jargon and a catalogue. The rigour is not the problem; the ordering is.
What changed
1. Tagline leads with the outcome.
Those last three are what a shopper checks first, so they are stated first.
2. Deleted a duplicate that was standing in the way. The seven-line stack block at the top duplicated the
## The rest of the stacksection that already exists at L535. Collapsed to one line + link.3. A "What you get" list in plain language — memory across sessions, it forgets on purpose, a wiki that writes itself, you can audit any answer, it works with your host.
4. The position, named.
Sovereignty is a present fact; eco-responsibility is an intent. The two are worded differently on purpose, and neither is inflated into the other.
Every restated claim verified at source
Nothing here is new prose over unchecked facts:
infrastructure/embedding_engine.py:97—all-MiniLM-L6-v2PRIVACY.mddocs/mcp-tools.md/whyreceiptscommands/why.mdLICENSE.claude-plugin/plugin.json— 9 entries across 6 events (SessionStart 1, UserPromptSubmit 1, PostToolUse 4, SessionEnd 1, Notification 1, SubagentStart 1)That last one was a pre-existing figure I was about to carry over on trust; it holds.
python3 scripts/check_doc_claims.pyexits 0. Documentation only — no code touched.Deliberately not in scope
"Where it stands" vs mem0 / basic-memory / OpenMemory is deferred at your request. For the record:
harness-comparisonexplicitly forbids a fixed product shootout ("not a static product shootout"), and I have no measurements of those products — a comparison table would have to be invented. Whenever you want to pick that up, we do it on measurements.🤖 Generated with Claude Code
https://claude.ai/code/session_01StMBvNd7eVJGtpnC2zNsx1
Generated by Claude Code