Skip to content

Commit f20cb17

Browse files
cdeustclaude
andcommitted
docs: layer the three positions and marketplace sections onto the welcoming 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]>
1 parent 0571343 commit f20cb17

1 file changed

Lines changed: 236 additions & 11 deletions

File tree

‎README.md‎

Lines changed: 236 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -21,8 +21,30 @@
2121
Runs locally by default. No account, no API key, no server to manage.
2222
</p>
2323

24+
<p align="center">
25+
<sub><em><strong>Independent project:</strong> Cortex is an independent, open-source project. It is <strong>not an Anthropic product</strong> and is not affiliated with, sponsored by, or endorsed by Anthropic.</em></sub>
26+
</p>
27+
2428
---
2529

30+
**Sovereign is what it is today.** Everything runs on your machine: a local SQLite file by
31+
default, or PostgreSQL + pgvector if you prefer. No LLM in the retrieval loop, and nothing
32+
leaves localhost unless you configure an integration that does. Your project's memory is a
33+
file you own and can delete.
34+
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.
38+
39+
**Eco-responsible is what we are aiming at.** Work that never reaches a datacenter is work
40+
nobody has to power, and an agent that finds the right context first time re-reads fewer
41+
files. We hold that intent to the
42+
[Green Software Foundation's SCI method](https://sci.greensoftware.foundation/), and we
43+
publish **no CO₂ or energy figure**, because we have not measured one.
44+
[What we do and do not claim ↓](#green-software-engineering)
45+
46+
> **36 neuroscience mechanisms · 52 memory tools · 9 lifecycle hooks · a self-curating per-project wiki — all local, all open-source, MIT.**
47+
2648
## Install
2749

2850
**Claude Code** — add the marketplace and install the plugin:
@@ -36,8 +58,12 @@ claude plugin install hypermnesia-mcp
3658
[Releases](https://github.com/cdeust/Cortex/releases) and open it, or use
3759
**Settings → Extensions**. The bundle carries the tools but no hooks; the MCPB format has none.
3860

61+
**Claude Cowork** is detected automatically (`CLAUDE_ENVIRONMENT=cowork`) and uses the local
62+
SQLite store. No PostgreSQL required.
63+
3964
**Any other stdio MCP host** (Codex, Gemini CLI, Cursor, Windsurf, VS Code) launches the same
40-
server and gets the same tools. Codex has a native package:
65+
server and gets the same tools. The per-host matrix and launch commands are in
66+
[Every other MCP host](#every-other-mcp-host) below. Codex has a native package:
4167
[docs/codex-plugin.md](docs/codex-plugin.md). WSL, TLS client certificates and corporate
4268
proxies are covered in [docs/deployment-scenarios.md](docs/deployment-scenarios.md).
4369

@@ -46,6 +72,10 @@ once when needed and then run offline. The embedding and reranking model files a
4672
on first use. Optional integrations, remote PostgreSQL, and OTLP telemetry use the network only
4773
when explicitly configured. [PRIVACY.md](PRIVACY.md) lists the exact scope.
4874

75+
An existing PostgreSQL install is never silently downgraded: the installer detects a
76+
configured `DATABASE_URL`, a prior backend marker, or a reachable local `cortex` database and
77+
keeps it across updates.
78+
4979
<details>
5080
<summary><strong>Upgrading from an older plugin identity</strong></summary>
5181

@@ -189,10 +219,6 @@ database shared across a team.
189219
bash <plugin-dir>/scripts/install-plugin.sh --postgres
190220
```
191221

192-
An existing PostgreSQL install is never silently downgraded: the installer detects a
193-
configured `DATABASE_URL`, a prior backend marker, or a reachable local `cortex` database and
194-
keeps it across updates.
195-
196222
| | SQLite (default) | PostgreSQL 15+ |
197223
|---|---|---|
198224
| Setup | none | pgvector, pg_trgm |
@@ -205,6 +231,127 @@ keeps it across updates.
205231
Three hook enrichments are PostgreSQL-only and degrade to silent no-ops on SQLite. Session
206232
banners, auto-recall, auto-capture, checkpoints and every memory tool work on both.
207233

234+
## Every other MCP host
235+
236+
The server is host-agnostic. Any host that can launch a stdio process gets the full tool
237+
surface on the default SQLite store. What is not portable are the nine lifecycle hooks, which
238+
are Claude Code plugin machinery; the server never imports or requires them at startup.
239+
240+
| Capability | Claude Code plugin | Local stdio hosts (Gemini CLI, Codex CLI, ChatGPT desktop, Cursor, Windsurf, VS Code, Agents SDK) | ChatGPT web |
241+
|---|---|---|---|
242+
| All 52 memory tools (`remember`, `recall`, wiki, navigation, consolidation, triggers, rules) | ✅ | ✅ | ❌ no remote HTTPS endpoint is shipped |
243+
| SQLite default store / PostgreSQL opt-in | ✅ | ✅ | ❌ would need a remote deployment and a per-user storage and auth model |
244+
| Auto-capture of significant tool output | ✅ PostToolUse hook | ❌ store explicitly with `remember` | ❌ |
245+
| Session-start context injection | ✅ SessionStart hook | ❌ call `recall` yourself | ❌ |
246+
| Per-prompt auto-recall | ✅ | ❌ | ❌ |
247+
| Compaction checkpoints | ✅ | ❌ | ❌ |
248+
| Autonomous wiki cycle | ✅ | ❌ run `consolidate` / `curate_wiki` manually | ❌ |
249+
| Cognitive profiling (`query_methodology`) | ✅ | ⚠️ profiles are mined from Claude Code session logs under `~/.claude/`; without them the profile is empty | ❌ |
250+
251+
On Claude Code memory is ambient: hooks capture and inject automatically. On every other host
252+
memory is tool-driven: the agent stores and retrieves when instructed, and nothing happens
253+
between prompts.
254+
255+
The launch command on every host is the PyPI package. The `[sqlite]` extra enables
256+
sqlite-vec vector search; without it the store still works, with vector search disabled.
257+
258+
```bash
259+
uvx --from "hypermnesia-mcp[sqlite]" hypermnesia-mcp
260+
```
261+
262+
**Gemini CLI** ships as an extension (`gemini-extension.json` is in this repository):
263+
264+
```bash
265+
gemini extensions install https://github.com/cdeust/Cortex
266+
```
267+
268+
**Codex and ChatGPT desktop** have a native plugin with a 10-tool lean surface. Pre-install
269+
the package once so the plugin's first `uvx` handshake reuses the local uv cache instead of
270+
spending its startup budget downloading a Python environment:
271+
272+
```bash
273+
uv tool install "hypermnesia-mcp[sqlite]"
274+
codex plugin marketplace add cdeust/Cortex
275+
codex plugin add hypermnesia-mcp-codex@cortex-codex-plugins
276+
```
277+
278+
The direct fallback registers the executable without the plugin:
279+
280+
```bash
281+
codex mcp add cortex --env CORTEX_MEMORY_STORE_BACKEND=sqlite -- hypermnesia-mcp
282+
```
283+
284+
The host boundary, the measured startup ceiling and the public-directory requirements Cortex
285+
deliberately does not claim are in [docs/codex-plugin.md](docs/codex-plugin.md).
286+
287+
## Green software engineering
288+
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.
320+
321+
### What has actually shipped
322+
323+
Efficiency work lands as ordinary reviewed PRs.
324+
325+
| Workstream | Change | PR |
326+
|---|---|---|
327+
| **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) |
329+
| | cache pinned dependency and actionlint downloads | [#477](https://github.com/cdeust/Cortex/pull/477) |
330+
| | sdist under 5 MB, with a byte-identical wheel | [#478](https://github.com/cdeust/Cortex/pull/478) |
331+
| | measured job timeouts; cancel superseded PR runs | [#479](https://github.com/cdeust/Cortex/pull/479) |
332+
| | bound the local Docker build context | [#481](https://github.com/cdeust/Cortex/pull/481) |
333+
| | stop exporting an unreadable layer cache on every PR run | [#506](https://github.com/cdeust/Cortex/pull/506) |
334+
| **Runtime** | defer unused pipeline hook imports | [#482](https://github.com/cdeust/Cortex/pull/482) |
335+
| | route PostToolUse hooks by the tool names they handle | [#483](https://github.com/cdeust/Cortex/pull/483) |
336+
| | audit and clean orphan plugin dependencies | [#484](https://github.com/cdeust/Cortex/pull/484) |
337+
| | rotate telemetry and detached-worker logs | [#485](https://github.com/cdeust/Cortex/pull/485) |
338+
| | 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) |
340+
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).
345+
346+
### Demand reduction is the primary lever
347+
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+
208355
## Under the hood
209356

210357
The mechanisms above are implemented as 36 system mechanisms spanning encoding, consolidation,
@@ -221,19 +368,97 @@ Clean Architecture, concentric layers: `server → handlers → core ← shared`
221368
## Limits worth knowing before you install
222369

223370
- The automatic behaviour is Claude Code plugin machinery. Elsewhere you call the tools
224-
yourself.
371+
yourself, and the host table above says exactly what is missing where.
225372
- SQLite fusion is in-process and unindexed. Fine at personal scale, slower at very large one.
226373
- The retrieval scores above are retrieval-only. They say nothing about answer quality.
227374
- Provenance grading is local and structural. It checks that a reference resolves, not that a
228375
claim is true; a DOI or arXiv link is never auto-verified.
376+
- No energy or carbon figure is published, for the reasons stated above.
229377
- First use downloads both the embedding and reranking model files. Optional integrations, remote
230378
PostgreSQL and OTLP telemetry add network activity only when explicitly configured; see
231379
[PRIVACY.md](PRIVACY.md).
232380

233-
## Project
381+
## Privacy Policy
382+
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)**.
234393

235-
[CHANGELOG.md](CHANGELOG.md) · [PRIVACY.md](PRIVACY.md) · [CONTRIBUTING.md](CONTRIBUTING.md) ·
236-
[SECURITY.md](SECURITY.md) · [benchmarks/](benchmarks/) · [docs/](docs/)
394+
## Support
237395

238-
Python 3.10+. MIT licensed. Issues and pull requests welcome; CONTRIBUTING.md describes the
239-
gates a change has to clear.
396+
- **Issues and bug reports:** [GitHub Issues](https://github.com/cdeust/Cortex/issues)
397+
- **Security disclosures:** see [SECURITY.md](SECURITY.md)
398+
- **Contact:** [[email protected]](mailto:[email protected])
399+
400+
## Development
401+
402+
```bash
403+
pytest # full suite; assets/badge-tests.svg carries the current count
404+
ruff check . && ruff format --check . # lint and format, both enforced in CI
405+
python scripts/check_doc_claims.py # advertised counts must match the repo
406+
python scripts/check_craftsmanship.py # file and method caps, layer whitelist, sourced constants
407+
```
408+
409+
[CONTRIBUTING.md](CONTRIBUTING.md) describes the gates a change has to clear.
410+
[GOVERNANCE.md](GOVERNANCE.md) says who decides and what happens if the maintainer stops.
411+
[docs/ROADMAP.md](docs/ROADMAP.md) says where the project is going, and
412+
[docs/ASSURANCE-CASE.md](docs/ASSURANCE-CASE.md) states the security argument and its limits.
413+
[CHANGELOG.md](CHANGELOG.md) is the complete release history.
414+
415+
## License
416+
417+
MIT, see [LICENSE](LICENSE).
418+
419+
This software is the independent work of Clément Deust. It was developed outside any
420+
employment relationship and is not affiliated with, endorsed by, or owned by any past or
421+
present employer. It is part of the ai-architect ecosystem
422+
([zetetic-team-subagents](https://github.com/cdeust/zetetic-team-subagents),
423+
[ai-architect-mcp-codebase](https://github.com/cdeust/ai-architect-mcp-codebase),
424+
[ai-architect-mcp-spec](https://github.com/cdeust/ai-architect-mcp-spec)).
425+
426+
The neuroscience and information-retrieval algorithms encoded in this software are derived
427+
from published academic work cited in
428+
[`docs/papers/bibliography.md`](docs/papers/bibliography.md) and inline in the source via
429+
`# source:` annotations (Friston on predictive coding, Anderson & Lebiere on rate-distortion
430+
forgetting, Nader et al. on retrieval-induced lability, McClelland et al. on consolidation,
431+
and others). The MIT license covers this implementation; it does not assert ownership over
432+
the underlying mechanisms, which remain attributable to their original authors and
433+
publications.
434+
435+
## Citation
436+
437+
The paper PDFs on `main` are the canonical artefacts (arXiv IDs forthcoming, endorsement in
438+
progress):
439+
440+
```bibtex
441+
@software{cortex2026,
442+
title={Cortex: Persistent Memory for Claude Code},
443+
author={Deust, Clement},
444+
year={2026},
445+
url={https://github.com/cdeust/Cortex}
446+
}
447+
448+
@unpublished{deust2026thermodynamic,
449+
title={Thermodynamic Memory vs. Flat-Importance Stores:
450+
Why Long-Term Retrieval Collapses Without Decay},
451+
author={Deust, Clement},
452+
year={2026},
453+
note={arXiv ID forthcoming, endorsement in progress},
454+
url={https://github.com/cdeust/Cortex/blob/main/docs/arxiv-thermodynamic/main.pdf}
455+
}
456+
457+
@unpublished{deust2026context,
458+
title={Stage-Aware Context Assembly for Long-Context Memory Retrieval},
459+
author={Deust, Clement},
460+
year={2026},
461+
note={arXiv ID forthcoming, endorsement in progress},
462+
url={https://github.com/cdeust/Cortex/blob/main/docs/arxiv-context-assembly/main.pdf}
463+
}
464+
```

0 commit comments

Comments
 (0)