You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit f20cb17
Browse filesBrowse the repository at this point in the historyBrowse files
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]>
Runs locally by default. No account, no API key, no server to manage.
22
22
</p>
23
23
24
+
<palign="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
+
24
28
---
25
29
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
+
26
48
## Install
27
49
28
50
**Claude Code** — add the marketplace and install the plugin:
@@ -36,8 +58,12 @@ claude plugin install hypermnesia-mcp
36
58
[Releases](https://github.com/cdeust/Cortex/releases) and open it, or use
37
59
**Settings → Extensions**. The bundle carries the tools but no hooks; the MCPB format has none.
38
60
61
+
**Claude Cowork** is detected automatically (`CLAUDE_ENVIRONMENT=cowork`) and uses the local
62
+
SQLite store. No PostgreSQL required.
63
+
39
64
**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:
41
67
[docs/codex-plugin.md](docs/codex-plugin.md). WSL, TLS client certificates and corporate
42
68
proxies are covered in [docs/deployment-scenarios.md](docs/deployment-scenarios.md).
43
69
@@ -46,6 +72,10 @@ once when needed and then run offline. The embedding and reranking model files a
46
72
on first use. Optional integrations, remote PostgreSQL, and OTLP telemetry use the network only
47
73
when explicitly configured. [PRIVACY.md](PRIVACY.md) lists the exact scope.
48
74
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
+
49
79
<details>
50
80
<summary><strong>Upgrading from an older plugin identity</strong></summary>
51
81
@@ -189,10 +219,6 @@ database shared across a team.
| 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.
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)|
|| 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)|
|| 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
+
208
355
## Under the hood
209
356
210
357
The mechanisms above are implemented as 36 system mechanisms spanning encoding, consolidation,
- 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.
225
372
- SQLite fusion is in-process and unindexed. Fine at personal scale, slower at very large one.
226
373
- The retrieval scores above are retrieval-only. They say nothing about answer quality.
227
374
- Provenance grading is local and structural. It checks that a reference resolves, not that a
228
375
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.
229
377
- First use downloads both the embedding and reranking model files. Optional integrations, remote
230
378
PostgreSQL and OTLP telemetry add network activity only when explicitly configured; see
231
379
[PRIVACY.md](PRIVACY.md).
232
380
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
0 commit comments