Skip to content

Commit ceb752f

Browse files
cdeustclaude
andcommitted
chore(mcp-directory): backport hypermnesia-mcp rename + directory-compliance bundle
Consolidates the cortex-official-mcp working tree onto main (base 9241ffd / #65), applied as a 33-file --binary patch via --3way (clean, no conflicts): - rename neuro-cortex-memory -> hypermnesia-mcp across pyproject.toml, manifest.json, server.json, plugin.json, package.json; install-plugin.sh keeps the intentional dual-cleanup of the legacy name; marketplace.json version_note left as history - MCP Directory submission bundle: server.json, manifest.json (12 tools annotated), icon.png, PRIVACY.md, .mcpbignore, mcp-name marker in README - docs/papers: science.md -> trimmed bibliography.md - infra/handlers carried from the #65 base (upstream_availability, pg_schema, pooled_sink, sqlite_store_search, staging_resolve_sink, tool_registry_ingest, ingest_codebase_schema, ingest_prd, wiki_adr) uv.lock regenerated (hypermnesia-mcp v3.23.0). Pyright per-rule ratchet: 568 errors == baseline 568, no blocking-rule regression (reportOptionalMemberAccess/Subscript 0). Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
1 parent 9241ffd commit ceb752f

34 files changed

Lines changed: 996 additions & 1375 deletions

‎.claude-plugin/marketplace.json‎

Lines changed: 2 additions & 2 deletions
Large diffs are not rendered by default.

‎.claude-plugin/plugin.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "cortex",
3-
"description": "Persistent memory for Claude Code — remembers across sessions automatically. Install and forget. Scientific retrieval backed by 41 published papers.",
3+
"description": "Persistent memory for Claude Code — remembers across sessions automatically. Install and forget. Scientific retrieval backed by 72 published references.",
44
"version": "3.23.0",
55
"author": {
66
"name": "Clement Deust",

‎.github/workflows/publish-ccplugins.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -200,7 +200,7 @@ jobs:
200200
- \`plugins/cortex/README.md\` — slim mirror pointing at canonical docs
201201
- \`README.md\` index entry under _${CATEGORY}_ (alphabetical)
202202
203-
The plugin is a thin manifest; the actual code runs via \`uvx\` from the \`neuro-cortex-memory\` PyPI package, so there is nothing to vendor."
203+
The plugin is a thin manifest; the actual code runs via \`uvx\` from the \`hypermnesia-mcp\` PyPI package, so there is nothing to vendor."
204204
if [ -n "$EXISTING" ]; then
205205
echo "Updating existing PR #$EXISTING"
206206
gh pr edit "$EXISTING" --repo $UPSTREAM --body "$BODY"

‎.github/workflows/release.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -148,7 +148,7 @@ jobs:
148148
# environment=pypi). This is the same entry that published <= 3.14.7.
149149
environment:
150150
name: pypi
151-
url: https://pypi.org/p/neuro-cortex-memory
151+
url: https://pypi.org/p/hypermnesia-mcp
152152
permissions:
153153
id-token: write
154154
steps:

‎.gitignore‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,8 @@ htmlcov/
77
dist/
88
build/
99
.pytest_cache/
10+
# Built MCPB bundle — release artifact attached to GitHub Releases, never committed
11+
*.mcpb
1012
.python-version
1113
.DS_Store
1214
mcp-server_old/
@@ -47,9 +49,10 @@ pyright-*.json
4749
# Runtime telemetry
4850
traces/
4951

50-
# Claude Code ephemeral session state
51-
.claude/scheduled_tasks.lock
52-
.claude/session-cache.json
52+
# Internal dev tooling, agent config & task notes — excluded from the public
53+
# submission repo (untracked via `git rm --cached`; kept locally on disk)
54+
.claude/
55+
tasks/
5356
benchmarks/snapshots/
5457
.memsearch/
5558

‎.mcpbignore‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# Cortex MCPB bundle — exclude everything not needed to run the uv server.
2+
# The `uv` runtime resolves dependencies from pyproject.toml + uv.lock at
3+
# install time, so the virtualenv and all dev / research / CI assets are
4+
# excluded from the bundle. Keep: manifest.json, pyproject.toml, uv.lock,
5+
# icon.png, mcp_server/, assets/banner.svg, README.md, LICENSE, PRIVACY.md.
6+
7+
# Virtual env & caches (deps resolved at install via uv, not bundled)
8+
.venv/
9+
__pycache__/
10+
*.pyc
11+
*.pyo
12+
.pytest_cache/
13+
.ruff_cache/
14+
.mypy_cache/
15+
16+
# VCS & CI
17+
.git/
18+
.github/
19+
.gitignore
20+
.npmignore
21+
.dockerignore
22+
.mcpbignore
23+
24+
# Heavy / irrelevant content
25+
benchmarks/
26+
video/
27+
docs/
28+
tasks/
29+
tests_py/
30+
tests_js/
31+
_pipeline/
32+
.claude/
33+
34+
# Claude Code plugin assets (not used by the MCPB / uv server runtime)
35+
.claude-plugin/
36+
agents/
37+
commands/
38+
skills/
39+
scripts/
40+
docker/
41+
Dockerfile
42+
43+
# Build artifacts
44+
dist/
45+
build/
46+
*.whl
47+
*.tar.gz
48+
*.egg-info/
49+
*.mcpb
50+
51+
# Repo-meta files not needed at runtime
52+
CHANGELOG.md
53+
CODE_OF_CONDUCT.md
54+
CONTRIBUTING.md
55+
SECURITY.md
56+
typecheck-baseline.json
57+
pyrightconfig.json
58+
glama.json
59+
package.json

‎CLAUDE.md‎

Lines changed: 44 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -132,7 +132,7 @@ Handlers are the **composition roots**: they wire infrastructure (I/O) to core (
132132
- `two_stage_transfer.py` — Transfer protocol execution
133133
- `emergence_tracker.py` — System-level metrics: forgetting curve, spacing effect, schema acceleration
134134
- `emergence_metrics.py` — Emergence metric definitions
135-
- `ablation.py` — Lesion study framework for 23 ablatable mechanisms
135+
- `ablation.py` — Lesion study framework (28 ablatable units spanning the 23 neuroscience-grounded mechanisms)
136136
- `ablation_report.py` — Ablation report generation
137137

138138
*Consolidation:*
@@ -207,7 +207,7 @@ Handlers are the **composition roots**: they wire infrastructure (I/O) to core (
207207
- `artifact_store.py` — Content-addressed raw-output artifacts (`~/.claude/methodology/artifacts/<yyyy-mm>/<sha256[:16]>.md`) backing gist+pointer memories
208208
- `agent_config.py` — Agent configuration and topic scoping
209209

210-
**handlers/** — Composition roots (33 tools + helpers, one per tool)
210+
**handlers/** — Composition roots (43 standalone tools + 3 upstream-integration tools conditionally registered = 46 total + helpers, one per tool)
211211

212212
**validation/** — `schemas.py` — Per-tool argument validation
213213

@@ -248,6 +248,8 @@ stack (galaxy/trace/wiki/knowledge/board UI) was extracted to the standalone
248248
| `seed_project` | 5-stage codebase bootstrap | varies |
249249
| `anchor` | Mark memory as compaction-resistant (heat=1.0) | <50ms |
250250
| `backfill_memories` | Auto-import prior Claude Code conversations | varies |
251+
| `unified_search` | Unified retrieval across memories, wiki, and code graph | <200ms |
252+
| `get_telemetry` | Retrieval and memory-system telemetry metrics | <50ms |
251253

252254
### Tier 2 — Navigation & Exploration (5 tools)
253255

@@ -259,7 +261,7 @@ stack (galaxy/trace/wiki/knowledge/board UI) was extracted to the standalone
259261
| `get_causal_chain` | Trace entity relationships through knowledge graph | <200ms |
260262
| `detect_gaps` | Identify isolated entities, sparse domains, temporal drift | <500ms |
261263

262-
### Tier 3 — Automation & Intelligence (7 tools)
264+
### Tier 3 — Automation & Intelligence (8 tools)
263265

264266
| Tool | Purpose | Target Latency |
265267
|---|---|---|
@@ -269,7 +271,30 @@ stack (galaxy/trace/wiki/knowledge/board UI) was extracted to the standalone
269271
| `get_rules` | List active rules by scope/type | <50ms |
270272
| `get_project_story` | Period-based autobiographical narrative | <500ms |
271273
| `assess_coverage` | Knowledge coverage score (0-100) + recommendations | <500ms |
272-
| `run_pipeline` | Drive ai-architect pipeline end-to-end (11 stages → PR) | varies |
274+
| `codebase_analyze` | Native AST codebase analysis (tree-sitter, 7 languages) | varies |
275+
| `curate_wiki` | Auto-curate wiki pages from memory clusters | varies |
276+
277+
### Tier 4 — Wiki (9 tools)
278+
279+
| Tool | Purpose | Target Latency |
280+
|---|---|---|
281+
| `wiki_write` | Create a first-class wiki page (ADR, spec, note) | <100ms |
282+
| `wiki_read` | Read a wiki page | <50ms |
283+
| `wiki_list` | List wiki pages by scope/kind | <50ms |
284+
| `wiki_link` | Create a typed link between wiki pages | <50ms |
285+
| `wiki_adr` | Create an Architecture Decision Record | <100ms |
286+
| `wiki_rename` | Rename a wiki page and update backlinks | <100ms |
287+
| `wiki_verify` | Verify wiki page integrity and links | <100ms |
288+
| `wiki_reindex` | Reindex wiki pages into memory pointers | varies |
289+
| `wiki_purge` | Permanently delete a wiki page | <50ms |
290+
291+
**Upstream-integration tools (3, conditionally registered)** — these register
292+
only when their upstream MCP server is configured, bringing the total to 46:
293+
`ingest_codebase` + `change_impact` (automatised-pipeline) and `ingest_prd`
294+
(prd-spec-generator). With no upstream present, exactly the **43 standalone
295+
tools** above register. Driving the ai-architect pipeline end-to-end
296+
(formerly `run_pipeline`) is **not** part of this server — it lives in the
297+
automatised-pipeline MCP.
273298

274299
## Slash Commands
275300

@@ -307,7 +332,7 @@ stack (galaxy/trace/wiki/knowledge/board UI) was extracted to the standalone
307332
## Testing
308333

309334
```bash
310-
pytest # All tests (2500+ passing)
335+
pytest # All tests (3000+ passing)
311336
pytest --cov=mcp_server --cov-report=term-missing # With coverage
312337
pytest tests_py/core/ # Core layer only
313338
pytest tests_py/shared/ # Shared layer only
@@ -332,21 +357,23 @@ python3 benchmarks/evermembench/run_benchmark.py # EverMemBen
332357
python3 benchmarks/episodic/run_benchmark.py --events 20 # Episodic Memories (ICLR 2025)
333358
```
334359

335-
**Current benchmark scores (clean DB, 2026-06-10, post bounded-io Phase 2):**
360+
**Current benchmark scores (E1 v3; canonical source: the arxiv papers under `docs/arxiv-thermodynamic/` and `docs/arxiv-context-assembly/`):**
336361
| Benchmark | Cortex | Best in paper |
337362
|---|---|---|
338363
| LongMemEval R@10 | **98.4%** | 78.4% |
339-
| LongMemEval MRR | **0.916** | -- |
340-
| LoCoMo R@10 | **94.1%** (1982 Qs) | -- |
341-
| LoCoMo MRR | **0.828** | 0.794 |
342-
| BEAM 100K MRR | **0.501** (395 Qs) | 0.329 |
343-
344-
BEAM note: the April 2026 record (0.591) was a 200-question split; the 100K
345-
split now loads 395 questions, so the absolute number re-based. A/B on the
346-
395-Q dataset (2026-06-10): pre-Phase-2 scoring 0.502 vs post 0.501 — the
347-
Phase 2 scoring changes are regression-free (Δ within noise), as predicted
348-
by their structural benchmark-neutrality (fixtures never use
349-
source='post_tool_capture', no prospective triggers, confidence=1.0).
364+
| LongMemEval MRR | **0.9124** | -- |
365+
| LoCoMo R@10 | **94.2%** | -- |
366+
| LoCoMo MRR | **0.8278** | 0.794 |
367+
| BEAM-100K MRR (retrieval-proxy) | **0.591** | -- |
368+
369+
BEAM note: 0.591 is a retrieval-proxy MRR (the rank of the first gold-matching
370+
memory), which is **not** commensurable with BEAM's end-to-end LLM-as-judge
371+
metric; no head-to-head BEAM claim is made — it is used only for within-system,
372+
same-harness comparisons. The context-assembly architecture adds +33.4% on
373+
BEAM-10M with label-free temporal stage detection (+21.5% with oracle labels).
374+
Source of truth: `docs/arxiv-thermodynamic/main.pdf` and
375+
`docs/arxiv-context-assembly/main.pdf` (the CLAUDE.md numbers must match the
376+
papers, not the other way around).
350377

351378
## Research-Driven Improvement Workflow
352379

‎CONTRIBUTING.md‎

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,20 @@
11
# Contributing to Cortex
22

33
Thanks for considering a contribution. Cortex is a persistent memory
4-
engine built on **20 biological mechanisms** with **41 academic citations**
4+
engine built on **23 biological mechanisms** with a **72-reference bibliography**
55
backing the algorithms. Every change is held to that bar.
66

77
---
88

99
## What this project is
1010

11-
A Python 3.10+ MCP server with **47 tools, 9 automatic hooks**, persisting
12-
to PostgreSQL + pgvector. Implements rate-distortion forgetting,
11+
A Python 3.10+ MCP server with **43 standalone tools** (46 with the optional
12+
automatised-pipeline + prd-spec-generator integrations) and **9 automatic
13+
hooks**, persisting to PostgreSQL + pgvector. Implements rate-distortion forgetting,
1314
predictive-coding write gating, retrieval-induced reconsolidation, pattern
1415
separation, sleep-cycle consolidation, emotional-valence weighting, and
1516
more. See [README](README.md) for the full architecture and benchmark
16-
results (LongMemEval Recall@10 = 97.8%, LoCoMo Recall@10 = 92.6%, BEAM-10M
17+
results (LongMemEval Recall@10 = 98.4%, LoCoMo Recall@10 = 94.2%, BEAM-10M
1718
+33.4% over the published baseline).
1819

1920
---
@@ -34,9 +35,9 @@ pip install -e ".[postgresql,benchmarks,dev]"
3435
bash scripts/setup.sh # macOS / Linux
3536

3637
# Verify everything is wired
37-
uvx --python 3.13 --from "neuro-cortex-memory[postgresql]" cortex-doctor
38+
uvx --python 3.13 --from "hypermnesia-mcp[postgresql]" cortex-doctor
3839

39-
# Run tests (2500+ tests across functional + benchmark suites)
40+
# Run tests (3000+ tests across functional + benchmark suites)
4041
pytest
4142

4243
# Run a benchmark
@@ -62,7 +63,7 @@ A new mechanism PR must include:
6263

6364
1. **Primary citation.** What published neuroscience or cognitive-science
6465
work motivates this mechanism? Include the paper's bibliographic
65-
reference in `docs/papers/science.md`.
66+
reference in `docs/papers/bibliography.md`.
6667
2. **The mathematical form.** Equations or pseudocode showing the exact
6768
computation. If you're adapting an algorithm from the literature,
6869
call out the divergence and justify it.
@@ -132,7 +133,7 @@ per run.
132133

133134
## Adding an MCP tool
134135

135-
47 tools currently. Adding a new one:
136+
43 standalone tools currently (46 with the optional upstream integrations). Adding a new one:
136137

137138
1. **Define the JSON schema** in the tool's module-level decorator.
138139
2. **Implement the handler** following the `BaseTool` protocol.

‎Dockerfile‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,7 @@ HEALTHCHECK --interval=30s --timeout=10s --retries=3 \
5757
# MCP servers typically run stdio transport; no ports to expose.
5858
# Prometheus metrics endpoint is served by the sidecar in Phase 7.1.
5959
#
60-
# Use `python -m mcp_server` because pyproject.toml registers only one
61-
# console script (`cortex-doctor`); there is no `neuro-cortex-memory`
62-
# entry point. The package's __main__.py documents this invocation.
60+
# Use `python -m mcp_server` — the invocation documented in the package's
61+
# __main__.py — so the image never depends on a console-script name
62+
# (`hypermnesia-mcp` / `cortex-doctor`) staying stable across renames.
6363
ENTRYPOINT ["python", "-m", "mcp_server"]

‎PRIVACY.md‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
# Privacy Policy — Cortex (hypermnesia-mcp)
2+
3+
_Last updated: 2026-06-18_
4+
5+
Cortex is a **local-first** memory server for Claude. It is designed so that your
6+
data stays on your machine. This policy describes exactly what data Cortex
7+
handles, where it is stored, and what (if anything) leaves your device.
8+
9+
## What data Cortex processes
10+
11+
To build and retrieve memory, Cortex reads and processes:
12+
13+
- **Claude Code session data** on your machine under `~/.claude/` — conversation
14+
transcripts (`projects/*/**.jsonl`), memory notes (`*.md`), and session logs.
15+
- **Content you explicitly store** via the `remember`, `wiki_write`, `anchor`,
16+
and ingestion tools (decisions, lessons, notes, code/PRD references).
17+
- **Derived metadata** — keyword/entity extraction, embeddings, heat/decay
18+
scores, and cognitive-profile statistics computed from the above.
19+
20+
Cortex does **not** ask for, collect, or process passwords, payment data, or
21+
credentials. If you place such data into a memory yourself, it is stored exactly
22+
like any other memory (locally) — avoid doing so.
23+
24+
## Where your data is stored
25+
26+
- **Default (SQLite):** all memories, entities, the knowledge graph, and profiles
27+
are stored in a single local database file at
28+
`~/.claude/methodology/memory.db`. Nothing is uploaded.
29+
- **Optional (PostgreSQL):** if you explicitly configure a PostgreSQL + pgvector
30+
database (via the `database_url` setting), your data is stored in **your own**
31+
database. Cortex never provisions or connects to any database you did not
32+
configure.
33+
34+
You own this data. Deleting the database file (or the relevant rows) permanently
35+
removes it. The `forget` tool deletes individual memories.
36+
37+
## What leaves your machine
38+
39+
Cortex itself does **not** transmit your memories, conversations, profiles, or
40+
any personal content to the author, to Anthropic, or to third-party analytics.
41+
There is no telemetry phone-home; the `get_telemetry` tool reports **local**
42+
performance statistics only.
43+
44+
The only outbound network activity is:
45+
46+
1. **One-time model download.** On first use, the open-source embedding model
47+
(`sentence-transformers`, all-MiniLM-L6-v2) and the reranking model
48+
(`flashrank`, ms-marco-MiniLM) are downloaded from the public Hugging Face
49+
model hub. These transfers fetch **model files only** — no user content is
50+
sent. After the first download the models run fully offline.
51+
2. **Integrations you explicitly enable.** If you configure optional upstream MCP
52+
servers or a remote PostgreSQL database, Cortex communicates only with the
53+
endpoints you provided.
54+
55+
## Data sharing
56+
57+
Cortex does not sell, share, or disclose your data to any third party. There are
58+
no third-party trackers, advertising SDKs, or analytics services in the server.
59+
60+
## Data retention
61+
62+
Data persists in your local store until you delete it. Cortex applies a local
63+
thermodynamic decay/consolidation process that compresses or prunes low-value
64+
memories over time; this is a local maintenance operation, not a transfer.
65+
66+
## Your controls
67+
68+
- `forget` — delete a specific memory.
69+
- Delete `~/.claude/methodology/memory.db` — remove all SQLite-stored data.
70+
- For PostgreSQL, manage retention directly in your database.
71+
72+
## Contact
73+
74+
Questions about this policy: **[email protected]** ·
75+
issues: https://github.com/cdeust/Cortex/issues

0 commit comments

Comments
 (0)