Cortex — Cowork Edition

Persistent memory for Claude Code in sandboxed environments

SQLite storage, no PostgreSQL required. Works in Claude Cowork sandboxed environments.

Running locally with PostgreSQL? Use Cortex instead for full capabilities including the neural graph visualization.

---

Getting Started

claude plugin marketplace add cdeust/Cortex-cowork
claude plugin install cortex-cowork

Restart your Claude Code session, then run:

/cortex-setup-project

That's it. SQLite database created automatically, no external dependencies.

---

What Works

Feature	Status
Remember / Recall	Full support (SQLite + sqlite-vec)
Codebase seeding	Full support
Session backfill	Full support
Cognitive profiling	Full support
Lifecycle hooks	Full support (7 hooks)
Consolidation (decay, compression, CLS)	Full support
Knowledge graph (entities, relationships)	Full support
Causal chains, gap detection	Full support
Agent team memory (transactive)	Full support
Wiki layer (Markdown, ADRs, backlinks)	Full support (new)
Structured context assembly (BEAM-10M)	Full support (new)
MMR diversity reranking	Full support (new)
Abstention gate (low-confidence filter)	Full support (new)
Emotional tagging / amygdala priority	Full support (new)
Temporal assembler (chronological intent)	Full support (new)
Neural graph visualization	Not available (requires PostgreSQL)
FlashRank reranking	Not available (ONNX dependency)

---

Synced from Upstream Cortex

Cortex-cowork now tracks the same cognitive and retrieval modules as the full Cortex release, adapted to run entirely on SQLite. Recent upstream features brought in:

Retrieval quality

• Structured context assembly (core/context_assembly/) — stage detection, PPR graph traversal, active retrieval, submodular coverage, budget-aware condensers. Delivered +21.5% on the BEAM-10M benchmark upstream.
• Temporal assembler — chronological reranking for event-ordering and summarization queries. Upstream measured +33.4% MRR on BEAM-10M.
• MMR diversity (core/mmr_diversity.py) — Maximal Marginal Relevance reranking to avoid near-duplicate results.
• Abstention gate (core/abstention_gate.py) — filters low-confidence retrievals instead of returning confidently wrong answers.
• Intent-aware recall — knowledge_update and multi_hop intents now route through dedicated weight profiles.

Memory quality

• Emotional tagging — amygdala-inspired priority encoding with Yerkes-Dodson curve (Wang & Bhatt 2024).
• Enhanced reconsolidation — returns ReconsolidationResult with emotional multiplier and strength delta; modulates on retrieval with prediction error.
• Structure-aware memory decomposition — atomic decomposition of complex memories before gate evaluation.
• Knowledge graph filtering — noise entities filtered during extraction (fixed upstream in 9c36b31).

Wiki layer

First-class Markdown authoring layer, not a PG projection. Six new MCP tools:

• wiki_write, wiki_read, wiki_list, wiki_link, wiki_adr, wiki_reindex
• Backed by infrastructure/wiki_store.py, rendered via core/wiki_layout.py + wiki_pages.py + wiki_links.py
• hooks/wiki_distill.py auto-promotes decision-grade memories to the wiki during consolidation
• Companion skill: cortex-wiki-author for authoring ADRs and project narratives

Imports and history

• cortex-import skill — imports memories from claude-mem (SQLite), Claude Desktop, ChatGPT export, Gemini Takeout, Cursor, and Claude Code JSONL
• Enhanced backfill_memories for auto-import of prior Claude Code conversations

Infrastructure hardening

• Verbose PostgreSQL error reporting on fallback to SQLite
• CWE-78 URL allowlist in http_launcher.py (only 127.0.0.1:* URLs accepted by browser opener)
• Command-injection fixes in git_diff.py and subprocess callsites
• Improved MCP client lifecycle in mcp_client.py / mcp_client_pool.py

All of the above runs on SQLite — no PostgreSQL, no pgvector, no psycopg required. The cowork install flow is unchanged.

---

How It Works

Same architecture as Cortex with SQLite replacing PostgreSQL:

• Storage: SQLite with sqlite-vec for vector similarity search
• Runtime: CORTEX_RUNTIME=cowork set automatically by the plugin
• Retrieval: Intent-aware query routing, vector + FTS fusion, heat-weighted ranking, MMR diversity, abstention gating, structured context assembly
• Memory lifecycle: Thermodynamic heat/decay, predictive coding write gate, emotional tagging, dream cycle consolidation, auto-distill to wiki
• Authoring: First-class Markdown wiki layer for ADRs, project narratives, and backlinks

Hooks

Seven hooks integrate with Claude Code's lifecycle:

Hook	Event	What It Does
SessionStart	Session opens	Injects anchors + hot memories + checkpoint
UserPromptSubmit	Before response	Auto-recalls relevant memories
PostToolUse	After Edit/Write/Bash	Auto-captures significant actions
PostToolUse	After Edit/Write/Read	Primes related memories (spreading activation)
SessionEnd	Session closes	Dream cycle (decay, compress, CLS)
Compaction	Context compacts	Saves/restores checkpoint
SubagentStart	Agent spawned	Briefs agent with prior work

---

Differences from Full Cortex

	Cortex	Cortex-cowork
Storage	PostgreSQL + pgvector	SQLite + sqlite-vec
Vector index	HNSW (pgvector)	Flat scan (sqlite-vec)
Server-side fusion	PL/pgSQL stored procedures	Client-side Python
Reranking	FlashRank ONNX	Disabled
Neural graph	Full 3D visualization	Not available
Environment	CLI, Docker	Cowork, CLI

For large memory stores (1000+ memories), the full PostgreSQL version offers significantly faster retrieval via HNSW indexing and server-side fusion.

---

Scientific Foundation

Same 41 paper citations as the full version. See Cortex for the complete paper index.

---

License

MIT

Citation

@software{cortex2026,
  title={Cortex: Persistent Memory for Claude Code},
  author={Deust, Clement},
  year={2026},
  url={https://github.com/cdeust/Cortex}
}