{"id":47698254,"url":"https://github.com/cdeust/cortex","last_synced_at":"2026-04-08T23:01:47.494Z","repository":{"id":346266914,"uuid":"1185234162","full_name":"cdeust/Cortex","owner":"cdeust","description":"C.O.R.T.E.X. — Cognitive profiling system for Claude Code","archived":false,"fork":false,"pushed_at":"2026-04-02T23:46:57.000Z","size":15959,"stargazers_count":8,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-03T03:26:27.212Z","etag":null,"topics":["agent-memory-system","agent-skills","artificial-intelligence","causal-inference","claude-code","claude-code-plugin","cognitive-architecture","cognitive-science","hopfield-network","knowledge-representation","long-term-memory","mcp-client","mcp-server","model-context-protocol","neural-network","neuroscience","persistent-memory","predictive-coding","retrieval-augmented-generation","vector-search"],"latest_commit_sha":null,"homepage":"https://ai-architect.tools","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cdeust.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-18T11:24:37.000Z","updated_at":"2026-04-03T02:10:14.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/cdeust/Cortex","commit_stats":null,"previous_names":["cdeust/jarvis","cdeust/cortex"],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/cdeust/Cortex","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cdeust%2FCortex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cdeust%2FCortex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cdeust%2FCortex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cdeust%2FCortex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cdeust","download_url":"https://codeload.github.com/cdeust/Cortex/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cdeust%2FCortex/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31577448,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-08T14:31:17.711Z","status":"ssl_error","status_checked_at":"2026-04-08T14:31:17.202Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-memory-system","agent-skills","artificial-intelligence","causal-inference","claude-code","claude-code-plugin","cognitive-architecture","cognitive-science","hopfield-network","knowledge-representation","long-term-memory","mcp-client","mcp-server","model-context-protocol","neural-network","neuroscience","persistent-memory","predictive-coding","retrieval-augmented-generation","vector-search"],"created_at":"2026-04-02T16:56:42.754Z","updated_at":"2026-04-08T23:01:47.488Z","avatar_url":"https://github.com/cdeust.png","language":"Python","readme":"\u003cdiv align=\"center\"\u003e\n\n# Cortex\n\n### Persistent memory for Claude Code — built on neuroscience research, not guesswork\n\n[![CI](https://github.com/cdeust/Cortex/actions/workflows/ci.yml/badge.svg)](https://github.com/cdeust/Cortex/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://python.org)\n[![Tests](https://img.shields.io/badge/tests-2080_passing-brightgreen.svg)](#development)\n\nMemory that learns, consolidates, forgets intelligently, and surfaces the right context at the right time. Works standalone or with a team of specialized agents.\n\n[Getting Started](#getting-started) | [How It Works](#how-it-works) | [Neural Graph](#neural-graph) | [Agent Integration](#agent-integration) | [Benchmarks](#benchmarks) | [Scientific Foundation](#scientific-foundation)\n\n**Companion projects:**\n[cortex-beam-abstain](https://github.com/cdeust/cortex-know-when-to-stop-training-model) — community-trained retrieval abstention model for RAG systems\n| [zetetic-team-subagents](https://github.com/cdeust/zetetic-team-subagents) — specialist Claude Code agents Cortex orchestrates with\n\n\u003c/div\u003e\n\n---\n\n## Getting Started\n\n### Prerequisites\n\n- **Python 3.10+**\n- **PostgreSQL 15+** with [pgvector](https://github.com/pgvector/pgvector) and pg_trgm extensions\n- **Claude Code** CLI or desktop app\n\n### Option A — Claude Code Marketplace (recommended)\n\n```bash\nclaude plugin marketplace add cdeust/Cortex\nclaude plugin install cortex\n```\n\nRestart your Claude Code session, then run:\n\n```\n/cortex-setup-project\n```\n\nThis handles everything: PostgreSQL + pgvector installation, database creation, embedding model download, cognitive profile building from session history, codebase seeding, conversation import, and hook registration. Zero manual steps.\n\n\u003e **Using Claude Cowork?** Install [Cortex-cowork](https://github.com/cdeust/Cortex-cowork) instead — uses SQLite, no PostgreSQL required.\n\u003e\n\u003e ```bash\n\u003e claude plugin marketplace add cdeust/Cortex-cowork\n\u003e claude plugin install cortex-cowork\n\u003e ```\n\n### Option B — Standalone MCP (no plugin)\n\n```bash\nclaude mcp add cortex -- uvx --from \"neuro-cortex-memory[postgresql]\" neuro-cortex-memory\n```\n\nAdds Cortex as a standalone MCP server via [uvx](https://docs.astral.sh/uv/). No hooks, no skills — just the 33 MCP tools. Requires `uv` installed.\n\n### Option C — Clone + Setup Script\n\n```bash\ngit clone https://github.com/cdeust/Cortex.git\ncd Cortex\nbash scripts/setup.sh        # macOS / Linux\npython3 scripts/setup.py     # Windows / cross-platform\n```\n\nInstalls PostgreSQL + pgvector (Homebrew on macOS, apt/dnf on Linux), creates the database, downloads the embedding model (~100 MB). On Windows, install PostgreSQL manually first, then run `setup.py`. Restart Claude Code after setup.\n\n### Option D — Docker\n\n```bash\ngit clone https://github.com/cdeust/Cortex.git\ncd Cortex\n\ndocker build -t cortex-runtime -f docker/Dockerfile .\ndocker run -it \\\n  -v $(pwd):/workspace \\\n  -v cortex-pgdata:/var/lib/postgresql/17/data \\\n  -v ~/.claude:/home/cortex/.claude-host:ro \\\n  -v ~/.claude.json:/home/cortex/.claude-host-json/.claude.json:ro \\\n  cortex-runtime\n```\n\nThe container includes PostgreSQL 17, pgvector, the embedding model, and Claude Code. Data persists via the `cortex-pgdata` volume.\n\n### Option E — Manual Setup\n\n\u003cdetails\u003e\n\u003csummary\u003eStep-by-step instructions\u003c/summary\u003e\n\n**1. Install PostgreSQL + pgvector**\n\n```bash\n# macOS\nbrew install postgresql@17 pgvector\nbrew services start postgresql@17\n\n# Ubuntu/Debian\nsudo apt-get install postgresql postgresql-server-dev-all\nsudo apt-get install postgresql-17-pgvector\nsudo systemctl start postgresql\n```\n\n**2. Create the database**\n\n```bash\ncreatedb cortex\npsql cortex -c \"CREATE EXTENSION IF NOT EXISTS vector;\"\npsql cortex -c \"CREATE EXTENSION IF NOT EXISTS pg_trgm;\"\n```\n\n**3. Install Python dependencies**\n\n```bash\npip install -e \".[postgresql]\"\npip install sentence-transformers flashrank\n```\n\n**4. Initialize schema**\n\n```bash\nexport DATABASE_URL=postgresql://localhost:5432/cortex\npython3 -c \"\nfrom mcp_server.infrastructure.pg_schema import get_all_ddl\nfrom mcp_server.infrastructure.pg_store import PgStore\nimport asyncio\nasyncio.run(PgStore(database_url='$DATABASE_URL').initialize())\n\"\n```\n\n**5. Pre-cache the embedding model**\n\n```bash\npython3 -c \"from sentence_transformers import SentenceTransformer; SentenceTransformer('all-MiniLM-L6-v2')\"\n```\n\n**6. Register MCP server**\n\n```bash\nclaude mcp add cortex -- uvx --from \"neuro-cortex-memory[postgresql]\" neuro-cortex-memory\n```\n\nRestart Claude Code to activate.\n\n\u003c/details\u003e\n\n### Verify Installation\n\nAfter setup, open Claude Code in any project. The SessionStart hook should inject context automatically. You can also test manually:\n\n```bash\npython3 -m mcp_server  # Should start on stdio without errors\n```\n\n### Configuration\n\nCortex reads `DATABASE_URL` from the environment (default: `postgresql://localhost:5432/cortex`). All tunable parameters use the `CORTEX_MEMORY_` prefix:\n\n| Variable | Default | What It Controls |\n|---|---|---|\n| `DATABASE_URL` | `postgresql://localhost:5432/cortex` | PostgreSQL connection string |\n| `CORTEX_RUNTIME` | auto-detected | `cli` (strict) or `cowork` (SQLite fallback) |\n| `CORTEX_MEMORY_DECAY_FACTOR` | 0.95 | Per-session heat decay rate |\n| `CORTEX_MEMORY_HOT_THRESHOLD` | 0.7 | Heat level considered \"hot\" |\n| `CORTEX_MEMORY_WRRF_VECTOR_WEIGHT` | 1.0 | Vector similarity weight in fusion |\n| `CORTEX_MEMORY_WRRF_FTS_WEIGHT` | 0.5 | Full-text search weight in fusion |\n| `CORTEX_MEMORY_WRRF_HEAT_WEIGHT` | 0.3 | Thermodynamic heat weight in fusion |\n| `CORTEX_MEMORY_DEFAULT_RECALL_LIMIT` | 10 | Max memories returned per query |\n\nSee `mcp_server/infrastructure/memory_config.py` for the full list (~40 parameters).\n\n---\n\n## How It Works\n\nCortex runs as an MCP server alongside Claude Code. It captures what you work on, consolidates it while you're away, and resurfaces the right context when you need it.\n\n### Memory is Invisible\n\nYou don't manage memory. Cortex does.\n\n**Session start** — hot memories, anchored decisions, and team context inject automatically. No manual recall needed.\n\n**During work** — PostToolUse hooks capture significant actions (edits, commands, test results). Decisions are auto-detected and protected from forgetting. File edits prime related memories via spreading activation so they surface in subsequent recall.\n\n**Session end** — a \"dream\" cycle runs automatically: decay old memories, compress verbose ones, and for long sessions, consolidate episodic memories into semantic knowledge (CLS).\n\n**Between sessions** — memories cool naturally (Ebbinghaus forgetting curve). Important ones stay hot. Protected decisions never decay.\n\n### Retrieval Pipeline\n\nSix signals fused server-side in PostgreSQL, then reranked client-side:\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"docs/diagram-retrieval-pipeline.svg\" alt=\"Retrieval pipeline: Intent → TMM fusion → FlashRank reranking\" width=\"80%\"/\u003e\n\u003c/p\u003e\n\n| Signal | Source | Paper |\n|---|---|---|\n| Vector similarity | pgvector HNSW (384-dim) | Bruch et al. 2023 |\n| Full-text search | tsvector + ts_rank_cd | Bruch et al. 2023 |\n| Trigram similarity | pg_trgm | Bruch et al. 2023 |\n| Thermodynamic heat | Ebbinghaus decay model | Ebbinghaus 1885 |\n| Recency | Exponential time decay | — |\n\n### Hooks\n\nSeven hooks integrate with Claude Code's lifecycle (managed via `plugin.json`, no manual setup):\n\n| Hook | Event | What It Does |\n|---|---|---|\n| **SessionStart** | Session opens | Injects anchors + hot memories + team decisions + checkpoint |\n| **UserPromptSubmit** | Before response | Auto-recalls relevant memories based on user's prompt |\n| **PostToolUse** | After Edit/Write/Bash | Auto-captures significant actions as memories |\n| **PostToolUse** | After Edit/Write/Read | Primes related memories via heat boost (spreading activation) |\n| **SessionEnd** | Session closes | Runs dream cycle (decay, compress, CLS based on activity) |\n| **Compaction** | Context compacts | Saves checkpoint; restores context after compaction |\n| **SubagentStart** | Agent spawned | Briefs agent with prior work + team decisions |\n\n---\n\n## Neural Graph\n\nLaunch the interactive visualization with `/cortex-visualize`. Three views: Graph, Board, and Pipeline.\n\n### Graph View\n\nForce-directed neural graph showing domain clusters, memories, entities, and discussions connected by typed edges.\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"docs/neural-graph-overview.png\" width=\"100%\" alt=\"Cortex Neural Graph — unified view with domain clusters, memories, entities, and discussions\" /\u003e\n\u003c/p\u003e\n\n### Board View\n\nMemories organized by biological consolidation stage. Each column shows decay rate, vulnerability, and plasticity. Memory cards display domain, heat, importance, and emotional tags.\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"docs/neural-graph-board.png\" width=\"100%\" alt=\"Cortex Board View — kanban consolidation stages with biological metrics\" /\u003e\n\u003c/p\u003e\n\n### Pipeline View\n\nHorizontal flow from domains through the write gate into consolidation stages. Block height reflects importance, color indicates domain.\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"docs/neural-graph-pipeline.png\" width=\"100%\" alt=\"Cortex Pipeline View — Sankey flow through consolidation stages\" /\u003e\n\u003c/p\u003e\n\n### Detail Panels\n\nClick any node for full context. Discussion nodes show session timeline, tools used, keywords, and a full conversation viewer. Memory nodes show biological meters (encoding strength, interference, schema match) and git diffs.\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"docs/neural-graph-discussion.png\" width=\"49%\" alt=\"Cortex — discussion detail with full conversation history\" /\u003e\n\u003cimg src=\"docs/neural-graph-diff.png\" width=\"49%\" alt=\"Cortex — code diff viewer in memory detail panel\" /\u003e\n\u003c/p\u003e\n\n### Filters\n\nDomain, emotion, and consolidation stage dropdowns. Toggle buttons for methodology, memories, knowledge, emotional nodes, protected/hot/global memories, and discussions.\n\n---\n\n## Agent Integration\n\nCortex is designed to work with a team of specialized agents. Each agent has scoped memory (`agent_topic`) while sharing critical decisions across the team.\n\n### Transactive Memory System\n\nBased on Wegner 1987: teams store more knowledge than individuals because each member specializes, and a shared directory tells everyone who knows what.\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"docs/diagram-team-memory.svg\" alt=\"Transactive Memory System — agent specialization, coordination, directory\" width=\"80%\"/\u003e\n\u003c/p\u003e\n\n**Specialization** — each agent writes to its own topic. Engineer's debugging notes don't clutter tester's recall.\n\n**Coordination** — decisions auto-protect and propagate. When engineer decides \"use Redis over Memcached,\" every agent sees it at next session start.\n\n**Directory** — entity-based queries span all topics. \"What do we know about the reranker?\" returns results from engineer, tester, and researcher.\n\n### Agent Briefing\n\nWhen the orchestrator spawns a specialist agent, the SubagentStart hook automatically:\n\n1. Extracts task keywords from the prompt\n2. Queries agent-scoped prior work (FTS, no embedding load needed)\n3. Fetches team decisions (protected + global memories from other agents)\n4. Injects as context prefix — agent starts with knowledge\n\n### Compatible Agent Team\n\nWorks with any custom Claude Code agents. See [zetetic-team-subagents](https://github.com/cdeust/zetetic-team-subagents) for a reference team of 18 specialists:\n\n| Agent | Specialty | Memory Topic |\n|---|---|---|\n| orchestrator | Parallel agent execution, coordination, merge | `orchestrator` |\n| engineer | Clean Architecture, SOLID, any language/stack | `engineer` |\n| architect | Module decomposition, layer boundaries, refactoring | `architect` |\n| code-reviewer | Clean Architecture enforcement, SOLID violations | `code-reviewer` |\n| test-engineer | Testing, CI verification, wiring checks | `test-engineer` |\n| dba | Schema design, query optimization, migrations | `dba` |\n| research-scientist | Benchmark improvement, neuroscience/IR papers | `research-scientist` |\n| frontend-engineer | React/TypeScript, component design, accessibility | `frontend-engineer` |\n| security-auditor | Threat modeling, OWASP, defense-in-depth | `security-auditor` |\n| devops-engineer | CI/CD, Docker, PostgreSQL provisioning | `devops-engineer` |\n| ux-designer | Usability, accessibility, design systems | `ux-designer` |\n| data-scientist | EDA, feature engineering, data quality, bias auditing | `data-scientist` |\n| experiment-runner | Ablation studies, hyperparameter search, statistical rigor | `experiment-runner` |\n| mlops | Training pipelines, model serving, GPU optimization | `mlops` |\n| paper-writer | Research paper structure, narrative flow, venue conventions | `paper-writer` |\n| reviewer-academic | Peer review simulation (NeurIPS/CVPR/ICML style) | `reviewer-academic` |\n| professor | Concept explanation, mental models, adaptive teaching | `professor` |\n| latex-engineer | LaTeX templates, figures, TikZ, bibliographies | `latex-engineer` |\n\n### Skills\n\nCortex ships as a Claude Code plugin with 14 skills:\n\n| Skill | Command | What It Does |\n|---|---|---|\n| cortex-remember | `/cortex-remember` | Store a memory with full write gate |\n| cortex-recall | `/cortex-recall` | Search memories with intent-adaptive retrieval |\n| cortex-consolidate | `/cortex-consolidate` | Run maintenance (decay, compress, CLS) |\n| cortex-explore-memory | `/cortex-explore-memory` | Navigate memory by entity/domain |\n| cortex-navigate-knowledge | `/cortex-navigate-knowledge` | Traverse knowledge graph |\n| cortex-debug-memory | `/cortex-debug-memory` | Diagnose memory system health |\n| cortex-visualize | `/cortex-visualize` | Launch 3D neural graph in browser |\n| cortex-profile | `/cortex-profile` | View cognitive methodology profile |\n| cortex-setup-project | `/cortex-setup-project` | Bootstrap a new project |\n| cortex-develop | `/cortex-develop` | Memory-assisted development workflow |\n| cortex-automate | `/cortex-automate` | Create prospective triggers |\n\n---\n\n## Benchmarks\n\nAll scores are **retrieval-only** — no LLM reader in the evaluation loop. We measure whether retrieval places correct evidence in the top results.\n\n### Running benchmarks from a fresh clone\n\nBenchmarks need extra dependencies beyond the core MCP server. Install them via the `benchmarks` extra:\n\n```bash\ngit clone https://github.com/cdeust/Cortex.git\ncd Cortex\npip install -e \".[postgresql,benchmarks,dev]\"\n```\n\nThis pulls in everything needed:\n- `datasets` — HuggingFace loader (BEAM, LoCoMo, LongMemEval auto-download)\n- `sentence-transformers` — `all-MiniLM-L6-v2` embeddings (~90 MB on first run)\n- `flashrank` — cross-encoder reranking (`ms-marco-MiniLM-L-12-v2`, ~30 MB)\n- `psycopg[binary]` + `pgvector` — PostgreSQL driver and vector similarity\n\nThen make sure PostgreSQL 15+ is running with `pgvector` and `pg_trgm` extensions, and `DATABASE_URL` points to it. The default is `postgresql://localhost:5432/cortex` — create the database with:\n\n```bash\ncreatedb cortex\npsql cortex -c \"CREATE EXTENSION IF NOT EXISTS vector;\"\npsql cortex -c \"CREATE EXTENSION IF NOT EXISTS pg_trgm;\"\n```\n\nRun a benchmark:\n\n```bash\n# BEAM (ICLR 2026) — 100K split, 20 conversations, ~10 min\npython benchmarks/beam/run_benchmark.py --split 100K\n\n# LoCoMo (ACL 2024) — 1986 questions, ~40 min\npython benchmarks/locomo/run_benchmark.py\n\n# LongMemEval (ICLR 2025) — 500 questions, ~45 min\npython benchmarks/longmemeval/run_benchmark.py --variant s\n```\n\n**If you skip the `[benchmarks]` extra**, you'll see catastrophically low scores because the embedder falls back to a hash-based stub (no semantic understanding) and FlashRank reranking is disabled. Always install the extra before running benchmarks.\n\n### Reported scores\n\n| Benchmark | Metric | Cortex | Best in Paper | Paper |\n|---|---|---|---|---|\n| LongMemEval | R@10 | **97.8%** | 78.4% | Wang et al., ICLR 2025 |\n| LongMemEval | MRR | **0.882** | — | |\n| LoCoMo | R@10 | **92.6%** | — | Maharana et al., ACL 2024 |\n| LoCoMo | MRR | **0.794** | — | |\n| BEAM | Overall MRR | **0.546** | 0.329 (LIGHT) | Tavakoli et al., ICLR 2026 |\n\n\u003e **Correction (April 2026):** Previously reported BEAM MRR of 0.627, LoCoMo MRR of 0.840, and LongMemEval MRR of 0.880 were measured on a polluted database — stale benchmark memories from prior runs were not properly purged between conversations, inflating retrieval scores with cross-conversation leakage. The root cause was a psycopg prepared statement cache invalidation bug (`cached plan must not change result type`) that silently prevented the benchmark cleanup function from executing after schema migrations. The bug has been fixed (stale plan recovery via `_execute()` wrapper + `DEALLOCATE ALL` after DDL). All scores above are from clean-database runs with verified per-conversation isolation.\n\n\u003cdetails\u003e\n\u003csummary\u003eAblation log — approaches tried and results\u003c/summary\u003e\n\n**Emotional memory processing (BEAM +0.038 MRR, shipped)**\n\n| Change | Paper | Result |\n|---|---|---|\n| Emotional retrieval signal (time-dependent multiplicative boost) | Yonelinas \u0026 Ritchey 2015 | +0.035 MRR, +5.1pp R@10 |\n| Time-dependent decay resistance | Yonelinas \u0026 Ritchey 2015 | Included in above |\n| Reconsolidation emotional boost + PE gate + age factor | Lee 2009, Osan-Tort-Amaral 2011, Milekic \u0026 Alberini 2002 | Included in above |\n\n**Event ordering + summarization intent (BEAM +0.003 MRR, shipped)**\n\n| Change | Paper | Result |\n|---|---|---|\n| EVENT_ORDER intent + chronological RRF reranking | ChronoRAG (Chen 2025), Cormack et al. (SIGIR 2009) | event_ordering 0.339→0.349 |\n| SUMMARIZATION intent detection | — | summarization 0.379→0.391 |\n\n**MMR diversity reranking (no improvement, disabled)**\n\n| Lambda | Summarization MRR | Overall MRR | Verdict |\n|---|---|---|---|\n| No MMR | **0.391** | **0.543** | Baseline |\n| 0.5 | 0.367 | 0.540 | Regression |\n| 0.7 | 0.381 | 0.538 | Regression |\n\nMMR (Carbonell \u0026 Goldstein, SIGIR 1998) trades precision for coverage. BEAM's MRR metric rewards first-hit position, so any diversity reranking hurts. Module kept (`mmr_diversity.py`) for future QA-based evaluation.\n\n**Instruction/preference typed retrieval (no improvement, stashed)**\n\nSix approaches tried to improve instruction_following (0.244) and preference_following (0.374):\n\n| Approach | Paper | Instruction | Preference | Overall | Verdict |\n|---|---|---|---|---|---|\n| Baseline (no type work) | — | 0.244 | 0.374 | 0.543 | — |\n| Tag boost in PL/pgSQL (weight 0.4) | ENGRAM | 0.245 | 0.370 | 0.540 | No help |\n| Tightened regex + gated type pool | ENGRAM, Searle 1969 | **0.245** | **0.390** | **0.546** | Best |\n| Centroid classifier (Snell 2017) + gated pool | Prototypical Networks | 0.241 | 0.357 | 0.544 | Slight regression |\n| Centroid ungated + insert at rank 1 | ENGRAM | 0.203 | 0.295 | 0.434 | **Destructive** |\n| Centroid ungated + append | ENGRAM | 0.241 | 0.372 | 0.545 | Neutral |\n| Centroid ungated + pre-rerank inject | ENGRAM | 0.241 | 0.375 | 0.544 | Neutral |\n\n**Root cause analysis:** BEAM instruction/preference queries look like normal questions (\"Could you show me how to implement a login feature?\") — not instruction-seeking queries. Intent classification cannot detect them because there's no instruction signal in the query. The answer should come from a stored instruction memory that is semantically close to the topic, but the standard WRRF retrieval already finds those memories — they just don't rank higher than episodic memories about the same topic. The problem is not recall (memories are found) but discrimination (instruction memories are indistinguishable from episodic memories by embedding similarity alone).\n\n**Open problem:** Instruction/preference retrieval requires either (a) a query-side classifier that detects \"this question would benefit from instruction context\" without keyword signals, or (b) a fundamentally different approach like ENGRAM's LLM-based routing at ingestion time. See [cortex-abstention](https://github.com/cdeust/cortex-abstention) for the community-driven model approach.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003ePer-category breakdowns\u003c/summary\u003e\n\n**BEAM (10 abilities, 395 questions, 100K split)**\n\n| Ability | MRR | R@10 |\n|---|---|---|\n| temporal_reasoning | 0.903 | 100.0% |\n| contradiction_resolution | 0.892 | 100.0% |\n| knowledge_update | 0.867 | 97.5% |\n| multi_session_reasoning | 0.742 | 95.0% |\n| information_extraction | 0.570 | 77.5% |\n| summarization | 0.391 | 66.7% |\n| preference_following | 0.374 | 72.5% |\n| event_ordering | 0.349 | 62.5% |\n| instruction_following | 0.244 | 52.5% |\n| abstention | 0.100 | 10.0% |\n\n**LongMemEval (6 categories, 500 questions)**\n\n| Category | MRR | R@10 |\n|---|---|---|\n| Single-session (assistant) | 0.982 | 100.0% |\n| Multi-session reasoning | 0.936 | 99.2% |\n| Knowledge updates | 0.921 | 100.0% |\n| Temporal reasoning | 0.857 | 97.7% |\n| Single-session (user) | 0.806 | 94.3% |\n| Single-session (preference) | 0.641 | 90.0% |\n\n**LoCoMo (5 categories, 1982 questions)**\n\n| Category | MRR | R@10 |\n|---|---|---|\n| adversarial | 0.855 | 93.9% |\n| open_domain | 0.835 | 95.0% |\n| multi_hop | 0.760 | 88.8% |\n| single_hop | 0.700 | 92.9% |\n| temporal | 0.539 | 77.2% |\n\n\u003c/details\u003e\n\n---\n\n## Architecture\n\nClean Architecture with strict dependency rules. Inner layers never import outer layers.\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"docs/diagram-architecture.svg\" alt=\"Clean Architecture layers\" width=\"80%\"/\u003e\n\u003c/p\u003e\n\n| Layer | Modules | Rule |\n|---|---|---|\n| **core/** | 118 | Pure business logic. Zero I/O. Imports only `shared/`. |\n| **infrastructure/** | 33 | All I/O: PostgreSQL, embeddings, file system. |\n| **handlers/** | 62 tools | Composition roots wiring core + infrastructure. |\n| **hooks/** | 7 | Lifecycle automation (SessionStart/End, PostToolUse, etc.) |\n| **shared/** | 12 | Pure utilities. Python stdlib only. |\n\n**Storage:** PostgreSQL 15+ with pgvector (HNSW) and pg_trgm. All retrieval in PL/pgSQL stored procedures.\n\n---\n\n## Scientific Foundation\n\n### The Zetetic Standard\n\nEvery algorithm, constant, and threshold traces to a published paper, a measured ablation, or documented engineering source. Nothing is guessed. Where engineering defaults exist, they are labeled as such.\n\n### Paper Index (41 citations)\n\n\u003cdetails\u003e\n\u003csummary\u003eInformation Retrieval\u003c/summary\u003e\n\n| Paper | Year | Venue | Module |\n|---|---|---|---|\n| Bruch et al. \"Fusion Functions for Hybrid Retrieval\" | 2023 | ACM TOIS | `pg_schema.py` |\n| Nogueira \u0026 Cho \"Passage Re-ranking with BERT\" | 2019 | arXiv | `reranker.py` |\n| Joren et al. \"Sufficient Context\" | 2025 | ICLR | `reranker.py` |\n| Collins \u0026 Loftus \"Spreading-activation theory\" | 1975 | Psych. Review | `spreading_activation.py` |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eNeuroscience — Encoding (5 papers)\u003c/summary\u003e\n\n| Paper | Year | Module |\n|---|---|---|\n| Friston \"A theory of cortical responses\" | 2005 | `hierarchical_predictive_coding.py` |\n| Bastos et al. \"Canonical microcircuits for predictive coding\" | 2012 | `hierarchical_predictive_coding.py` |\n| Wang \u0026 Bhatt \"Emotional modulation of memory\" | 2024 | `emotional_tagging.py` |\n| Doya \"Metalearning and neuromodulation\" | 2002 | `coupled_neuromodulation.py` |\n| Schultz \"Prediction and reward\" | 1997 | `coupled_neuromodulation.py` |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eNeuroscience — Consolidation (6 papers)\u003c/summary\u003e\n\n| Paper | Year | Module |\n|---|---|---|\n| Kandel \"Molecular biology of memory storage\" | 2001 | `cascade.py` |\n| McClelland et al. \"Complementary learning systems\" | 1995 | `dual_store_cls.py` |\n| Frey \u0026 Morris \"Synaptic tagging\" | 1997 | `synaptic_tagging.py` |\n| Josselyn \u0026 Tonegawa \"Memory engrams\" | 2020 | `engram.py` |\n| Dudai \"The restless engram\" | 2012 | `reconsolidation.py` |\n| Borbely \"Two-process model of sleep\" | 1982 | `session_lifecycle.py` |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eNeuroscience — Retrieval \u0026 Navigation (4 papers)\u003c/summary\u003e\n\n| Paper | Year | Module |\n|---|---|---|\n| Behrouz et al. \"Titans: Learning to Memorize at Test Time\" | 2025 | `titans_memory.py` |\n| Stachenfeld et al. \"Hippocampus as predictive map\" | 2017 | `cognitive_map.py` |\n| Ramsauer et al. \"Hopfield Networks is All You Need\" | 2021 | `hopfield.py` |\n| Kanerva \"Hyperdimensional computing\" | 2009 | `hdc_encoder.py` |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eNeuroscience — Plasticity \u0026 Maintenance (14 papers)\u003c/summary\u003e\n\n| Paper | Year | Module |\n|---|---|---|\n| Hasselmo \"Hippocampal theta rhythm\" | 2005 | `oscillatory_clock.py` |\n| Buzsaki \"Hippocampal sharp wave-ripple\" | 2015 | `oscillatory_clock.py` |\n| Leutgeb et al. \"Pattern separation in dentate gyrus\" | 2007 | `pattern_separation.py` |\n| Yassa \u0026 Stark \"Pattern separation in hippocampus\" | 2011 | `pattern_separation.py` |\n| Turrigiano \"The self-tuning neuron\" | 2008 | `homeostatic_plasticity.py` |\n| Abraham \u0026 Bear \"Metaplasticity\" | 1996 | `homeostatic_plasticity.py` |\n| Tse et al. \"Schemas and memory consolidation\" | 2007 | `schema_engine.py` |\n| Gilboa \u0026 Marlatte \"Neurobiology of schemas\" | 2017 | `schema_engine.py` |\n| Hebb *The Organization of Behavior* | 1949 | `synaptic_plasticity.py` |\n| Bi \u0026 Poo \"Synaptic modifications\" | 1998 | `synaptic_plasticity.py` |\n| Perea et al. \"Tripartite synapses\" | 2009 | `tripartite_synapse.py` |\n| Kastellakis et al. \"Synaptic clustering\" | 2015 | `dendritic_clusters.py` |\n| Wang et al. \"Microglia-mediated synapse elimination\" | 2020 | `microglial_pruning.py` |\n| Ebbinghaus *Memory* | 1885 | `thermodynamics.py` |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eTeam Memory \u0026 Preemptive Retrieval (6 papers)\u003c/summary\u003e\n\n| Paper | Year | Module |\n|---|---|---|\n| Wegner \"Transactive memory\" | 1987 | `memory_ingest.py`, `session_start.py` |\n| Zhang et al. \"Collaboration Mechanisms for LLM Agents\" | 2024 | `memory_ingest.py` |\n| McGaugh \"Amygdala modulates consolidation\" | 2004 | `memory_ingest.py` |\n| Adcock et al. \"Reward-motivated learning\" | 2006 | `memory_ingest.py` |\n| Bar \"The proactive brain\" | 2007 | `preemptive_context.py` |\n| Smith \u0026 Vela \"Context-dependent memory\" | 2001 | `agent_briefing.py` |\n\n\u003c/details\u003e\n\n### Ablation Data\n\nAll ablation results committed to `benchmarks/beam/ablation_results.json`.\n\n| Parameter | Tested Values | Optimal | Source |\n|---|---|---|---|\n| rerank_alpha | 0.30, 0.50, 0.55, 0.70 | **0.70** | BEAM 100K ablation |\n| FTS weight | 0.0, 0.3, 0.5, 0.7, 1.0 | 0.0 (BEAM), 0.5 (balanced) | Cross-benchmark |\n| Heat weight | 0.0, 0.1, 0.3, 0.5, 0.7 | 0.7 (BEAM), 0.3 (balanced) | Cross-benchmark |\n| Adaptive alpha | CE spread QPP | **Rejected** | Regressed LoCoMo -5.1pp R@10 |\n\n### Engineering Defaults\n\nValues without paper backing, explicitly documented:\n\n| Constant | Value | Location | Status |\n|---|---|---|---|\n| FTS weight | 0.5 | `pg_recall.py` | Balanced across benchmarks |\n| Heat weight | 0.3 | `pg_recall.py` | Balanced across benchmarks |\n| CE gate threshold | 0.15 | `reranker.py` | Engineering default |\n| Titans eta/theta | 0.9/0.01 | `titans_memory.py` | Paper uses learned params |\n\n---\n\n## Security\n\nCortex runs locally (MCP over stdio, PostgreSQL on localhost, visualization on 127.0.0.1). No data leaves your machine unless you explicitly configure an external database.\n\n### Audit Score: 91/100\n\n| Category | Score | Notes |\n|---|---|---|\n| Data Flow | 90 | No external data exfiltration. Embeddings computed locally. |\n| SQL Injection | 95 | All queries parameterized (psycopg `%s`). Dynamic columns use `sql.Identifier()`. |\n| Auth \u0026 Access Control | 85 | Docker PG uses `scram-sha-256` on localhost. MCP over stdio (no network auth needed). |\n| Dependency Health | 80 | Floor-pinned deps. Background install version-bounded. |\n| Network Behavior | 92 | Model download on first run only. Viz servers bind `127.0.0.1`. |\n| Code Quality | 90 | Pydantic validation on all tools. Input length limits on `remember`/`recall`. Path traversal protected. |\n| Prompt Injection | 88 | Memory content escaped in HTML rendering. Session injection uses data delimiters. |\n| Secrets Management | 90 | `.env`/credentials in `.gitignore`. No hardcoded secrets. Docker credentials via env vars. |\n\n\u003cdetails\u003e\n\u003csummary\u003eHardening measures\u003c/summary\u003e\n\n- SQL parameterization across all 7 `pg_store` modules (psycopg `%s` placeholders)\n- `sql.Identifier()` for dynamic column names (no f-string SQL)\n- ILIKE patterns escape `%`, `_`, `\\` from user input\n- CORS allows `*` (localhost-only servers, no external exposure)\n- Docker PostgreSQL uses `scram-sha-256` auth on `127.0.0.1/32`\n- `trust_remote_code` removed from embedding model loading\n- Input length validation: `remember` content capped at 50KB, queries at 10KB\n- Path traversal protection via `.resolve()` in `sync_instructions`\n- HTML escaping (`esc()`) on all user-generated content in visualization\n- Background `pip install` version-bounded (`\u003e=2.2.0,\u003c4.0.0`)\n- Secrets patterns (`.env`, `*.credentials.json`, `*.pem`, `*.key`) in `.gitignore`\n\n\u003c/details\u003e\n\n---\n\n## Development\n\n```bash\npytest                    # 2080 tests\nruff check .              # Lint\nruff format --check .     # Format\n```\n\n---\n\n## License\n\nMIT\n\n## Citation\n\n```bibtex\n@software{cortex2026,\n  title={Cortex: Persistent Memory for Claude Code},\n  author={Deust, Clement},\n  year={2026},\n  url={https://github.com/cdeust/Cortex}\n}\n```\n\u003c/div\u003e\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcdeust%2Fcortex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcdeust%2Fcortex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcdeust%2Fcortex/lists"}