Cortex v3.0.0 — Claude's Cognitive Layer

What's New in v3.0.0

Cortex v3.0.0 is a ground-up transformation of Claude's cognitive memory layer. Every major subsystem has been redesigned for reliability, performance, and correctness.

Highlights

• 7 Memory Adapters — warp-sqlite, episodic-memory, knowledge-graph, jsonl, vector, claudemd, gemini
• 447 Tests Passing across 22 test suites (up from 153 in v2.0)
• SQLite-backed storage — bi-temporal fields, confidence decay, write gates
• CortexRenderer — data-driven Clack-style terminal UI replacing neural-visuals
• HyDE Query Expansion — Hypothetical Document Embeddings for semantic search
• MCP Sampling — zero-cost LLM inference via Claude Code's built-in models
• Triple Hook Architecture — SessionStart, PreCompact, and Stop hooks

New Features

Core Infrastructure

• SQLite Adapters (core/sqlite-store.cjs) — 7 memory adapters with unified query interface
• Bi-temporal Memory — validFrom, validTo, ingestedAt fields on all memories
• Confidence Decay — type-specific half-lives (skills: 90d, patterns: 60d, decisions: 30d)
• Write Gate — 5-criteria quality filter preventing low-value memories from being stored
• API Key Setup — cortex setup-key command with validation and .env file management

Search & Intelligence

• HyDE Query Expansion — generates hypothetical answer documents for better semantic matching (Gao et al., 2022)
• HaikuWorker — dual-model architecture using Claude Haiku for query routing and intent classification
• SamplingAdapter — zero-cost MCP Sampling with automatic API fallback
• MCP Elicitation — interactive memory curation via the learn tool

Hooks

• PreCompact Hook — captures context before Claude Code compresses conversation history
• Stop Hook — continuous lightweight memory capture between major events
• SessionStart Hook — streaming adapter initialization with progress visualization

Visual Output

• CortexRenderer (hooks/cli-renderer.cjs) — pure data-driven renderer using @clack/prompts patterns
• Streaming progress bars per adapter with timing and cold-start markers
• Token budget visualization with configurable thresholds
• Clean Clack-style output with proper ANSI color support

Developer Experience

• Plugin Manifest (plugin.json) — one-click Claude Code plugin installation
• 22 Test Suites — comprehensive unit, integration, and e2e tests
• CI/CD — GitHub Actions testing on Node.js 18, 20, 22
• Demo Recording — tmux+asciinema+agg pipeline for headless GIF generation

Breaking Changes

• neural-visuals.cjs removed — replaced by cli-renderer.cjs
• Hook output format changed to use CortexRenderer data protocol
• SQLite schema requires migration from v2 (automatic on first run)

Stats

Metric	v2.0	v3.0
Test suites	4	22
Assertions	153	447
Memory adapters	3	7
Hooks	1	3
Source files	~40	97
Total lines	~15k	44,669

Installation

# Claude Code plugin (recommended)
claude mcp add cortex -- node ~/.claude/memory/index.cjs

# Or npm
npm install cortex-claude

---

Full Changelog: v2.0.0...v3.0.0

v3.0.1 - Fix memory persistence

Bug Fixes

Two critical bugs that caused zero memory persistence since v3.0.0:

1. Stop Hook Path Resolution (hooks/stop-hook.cjs)

The stop hook used a hardcoded fallback path (~/.claude/memory) instead of resolving relative to __dirname like all other hooks. This caused a split-brain: insights were written to a shadow directory that no other component reads from. 2329 bytes of real insights were silently lost.

Fix: Use path.dirname(__dirname) (matching session-start.cjs and session-end.cjs).

2. WriteGate Threshold Too Strict (core/write-gate.cjs)

The persistence thresholds (maxScore >= 0.5, totalScore > 1.5) were unreachable for real-world extractions. A pattern like "always add signal handlers" scored only 0.2 total (one keyword match at 0.2 each), resulting in 100% filter rate.

Fix: Lowered to maxScore >= 0.2, totalScore > 0.5. The extraction engine already pre-filters at 0.7 confidence, so the write gate now serves as a lightweight secondary filter.

Impact

Before this fix, Cortex appeared functional but persisted zero memories across sessions. After this fix, both the stop hook (every response) and session-end hook correctly write to the shared data directory.

Upgrade

cd ~/.claude/memory  # or your install path
git pull origin master

Or fresh install:

git clone https://github.com/robertogogoni/cortex-claude.git ~/.claude/memory
cd ~/.claude/memory && npm install

Cortex v2.0.0 - Claude's Cognitive Layer

Highlights

• Dual-Model Architecture: Haiku for fast queries ($0.001), Sonnet for deep reasoning ($0.01)
• 7 MCP Tools: query, recall, reflect, infer, learn, consolidate, health
• 7 MCP Resources: Dynamic discovery of memory layers, patterns, skills, projects
• 5 MCP Prompts: weekly-review, debug-checklist, session-summary, pattern-analysis, project-context
• Hybrid Vector Search: HNSW + BM25 with Reciprocal Rank Fusion (all-MiniLM-L6-v2, 384D)
• Auto-Extraction: Learns from every Claude Code session automatically
• Auto-Injection: Injects relevant memories at session start
• 3-Tier Memory: Working → Short-Term → Long-Term with quality-based promotion
• LADS Framework: Learnable, Adaptive, Documenting, Self-improving
• Neural Themes: 4 rotating visual themes with 120+ whimsical phrases
• AES-256-GCM Encryption: Secure memory storage
• 142/142 Tests Passing

Installation

git clone https://github.com/robertogogoni/cortex-claude.git ~/.claude/memory
cd ~/.claude/memory && npm install

See README.md for full setup (MCP server registration + hooks).

What's Next (v3.0 Roadmap)

• MCP Sampling (zero-cost LLM calls via host Claude)
• PreCompact hook (save context before window compression)
• Write gates (filter noise from extraction)
• Bi-temporal memory (valid-from/valid-to timestamps)
• Confidence decay (FSRS-6 inspired forgetting curves)
• Claude Code plugin packaging (one-command install)