Cortex — Persistent Memory Protocol for Claude Code

Infinite memory for Claude Code. Zero dependencies. Works automatically.

╔══════════════════════════════════════════════╗
║  Session #47 | 2026-03-18 14:30             ║
║  Focus: Implementing RetryWorker            ║
║  47 decisions | 23 patterns | 12 tasks      ║
║  Project healthy                            ║
╚══════════════════════════════════════════════╝

The Problem

Claude Code starts every session from scratch. It doesn't remember what you did yesterday, what architectural decision you made last week, or which bug took 3 hours to fix.

Existing solutions (claude-mem, Mem0, memory-bank) try to solve this with background servers, vector databases, MCP servers, and Agent SDK calls.

The result? Heavy dependencies, silent failures, and users reporting "I don't feel any difference".

The Cortex Solution

Cortex solves the problem in the simplest and most robust way possible:

| Approach | Claude-Mem | Mem0 | Cortex | |----------|-----------|------|--------| | Dependencies | Bun, Chroma, SQLite, Agent SDK | Cloud API, MCP server | Zero. Python 3.7+ (comes with the OS) | | Complexity | 9 hook scripts, HTTP worker | MCP + API key | 4 simple hooks | | Storage | SQLite + vector DB | Cloud | Markdown files (Git-versionable) | | Visibility | Web UI on port 37777 | Cloud dashboard | Readable files in your editor | | Cost | API calls for compression | Paid plan | $0 | | Works offline | No (needs API) | No (cloud) | Yes, 100% offline | | Survives /compact | Partially | Partially | Yes. CLAUDE.md reloads everything |

Why Markdown?

1. It's in context. CLAUDE.md is reloaded after /compact. Memory files referenced via hooks are injected automatically. Your memory NEVER gets lost.
2. It's versionable. Your decisions and patterns live in Git. git log .claude/memory/decisions.md shows the project's evolution.
3. It's readable. Open it in VSCode and SEE what Claude remembers. No interfaces, no dashboards.
4. It's editable. Want to fix a memory? Edit the file. No APIs, no UIs.

Installation

Requirements: Python 3.7+ (check with python3 --version or python --version)

Option 1: npx (easiest — any OS)

npx cortex-protocol /path/to/your/project

That's it. Works on Windows, Linux, and macOS. No cloning, no manual steps.

Option 2: Clone + Install

git clone https://github.com/diegoclementeasaas/cortex.git /tmp/cortex
python3 /tmp/cortex/install.py /path/to/your/project

Option 3: One-liner (Linux/Mac)

curl -fsSL https://raw.githubusercontent.com/diegoclementeasaas/cortex/main/install.sh | bash -s /path/to/your/project

Option 4: Windows (PowerShell)

git clone https://github.com/diegoclementeasaas/cortex.git $env:TEMP\cortex
python "$env:TEMP\cortex\install.py" "C:\path\to\your\project"

What the installer does

The installer works on any project — new or existing. It handles everything automatically:

| Step | New project | Existing project | |------|------------|-----------------| | Hooks (3 Python scripts) | Creates | Creates | | Commands (6 slash commands) | Creates | Creates | | Rules (memory protocol) | Creates | Creates | | Memory templates (5 files) | Creates | Skips (preserves your data) | | settings.json | Creates | Merges (adds Cortex hooks alongside yours) | | CLAUDE.md | Creates | Appends Cortex block (preserves your content) | | .gitignore | Creates | Appends Cortex rules | | cortex.json | Creates | Creates (version tracking) |

After installing, open Claude Code in your project and run:

/mem-init

This analyzes your project and initializes the memory files.

Updating

When a new version of Cortex is released:

npx cortex-protocol@latest --update /path/to/your/project

Or if you cloned the repo:

cd /tmp/cortex && git pull
python3 /tmp/cortex/install.py --update /path/to/your/project

Update replaces system files (hooks, commands, rules) with the latest version. Update preserves all your memory files (decisions, patterns, progress, etc.).

Uninstalling

npx cortex-protocol --uninstall /path/to/your/project

This removes:

• All Cortex hooks, commands, and rules
• Cortex hooks from settings.json (your other hooks stay intact)
• Cortex block from CLAUDE.md (your other content stays intact)
• The cortex.json manifest

This preserves all your memory files in .claude/memory/. Your data is never deleted.

Health Check

npx cortex-protocol --doctor /path/to/your/project

Checks: all system files present, hooks configured in settings.json, CLAUDE.md block present, Python available. Reports any issues and how to fix them.

Dry Run

Preview what any command will do without actually making changes:

npx cortex-protocol --dry-run /path/to/project             # preview install
npx cortex-protocol --update --dry-run /path/to/project    # preview update
npx cortex-protocol --uninstall --dry-run /path/to/project # preview uninstall

How It Works

Automatic Lifecycle

SESSION START
  Hook: cortex-session-start.py
  → Reads .claude/memory/*.md
  → Injects context into the conversation
  → Claude already knows: project, focus, decisions
          │
          ▼
DURING WORK
  CLAUDE.md rules + .claude/rules/
  → Claude writes memories IN REAL TIME
  → Decision made?    → Append to decisions.md
  → Bug fixed?        → Append to decisions.md [BUGFIX]
  → Pattern learned?  → Append to patterns.md
  → Task completed?   → Update progress.md
  → Confirms: "Registered in decisions.md"
          │
          ▼
STOP (before stopping response)
  Hook: echo [CORTEX-STOP]
  → Reminder to save pending memories
          │
          ▼
PRE-COMPACT (before /compact)
  Hook: cortex-pre-compact.py
  → Warning to save pending context
  → After compact: CLAUDE.md reloads protocol
          │
          ▼
SESSION END
  Hook: cortex-session-end.py
  → Increments session counter
  → Logs session end
  → Memories persist in .claude/memory/

File Structure

your-project/
├── CLAUDE.md                          # Cortex protocol (reloaded after compact)
├── .claude/
│   ├── cortex.json                   # Version manifest (created by installer)
│   ├── settings.json                 # Hooks configuration
│   ├── memory/
│   │   ├── MEMORY_BANK.md           # Project identity (stack, conventions)
│   │   ├── active-context.md         # Current state (overwritten each session)
│   │   ├── decisions.md              # Decision log (append-only)
│   │   ├── patterns.md              # Patterns and gotchas (append-only)
│   │   ├── progress.md              # Tasks and progress
│   │   └── archive/                  # Compacted old memories
│   ├── rules/
│   │   └── memory-protocol.md       # Enforcement rules
│   ├── commands/
│   │   ├── mem-init.md              # /mem-init
│   │   ├── mem-save.md              # /mem-save
│   │   ├── mem-status.md            # /mem-status
│   │   ├── mem-recall.md            # /mem-recall [topic]
│   │   ├── mem-compact.md           # /mem-compact
│   │   └── mem-reset.md             # /mem-reset
│   └── hooks/
│       ├── cortex-session-start.py   # Loads context automatically
│       ├── cortex-pre-compact.py     # Warning before compaction
│       └── cortex-session-end.py     # Log and counter

Commands

Use these inside Claude Code:

| Command | What it does | When to use | |---------|-------------|-------------| | /mem-init | Analyzes your project and initializes memory files | Once, after installing Cortex | | /mem-status | Shows memory dashboard (tokens, counts, health) | Anytime you want to check | | /mem-save | Forces save of all pending memories | Before ending an important session | | /mem-recall [topic] | Searches all memories for a topic | When you need something not in current context | | /mem-compact | Manually compacts old memories into archive | Rarely (auto-compact handles this) | | /mem-reset | Erases all memories and starts fresh (backs up first) | Emergency only |

Note: Commands are manual controls. The hooks handle everything automatically — SessionStart injects context, Stop reminds to save, PreCompact preserves before compaction, SessionEnd logs the session.

Configuration

The SessionStart hook supports 3 context injection strategies:

| Strategy | Tokens | What it injects | |----------|--------|----------------| | smart (default) | ~500 | active-context + project summary + last 5 decisions + last 5 patterns (GOTCHAs first) + active tasks | | full | ~800-2000+ | everything (grows with the project) | | minimal | ~200 | only active-context |

Auto-compact

SessionStart automatically checks if decisions.md or patterns.md exceeded the entry limit. If so, it archives the oldest entries to .claude/memory/archive/ before injecting context. No memory is lost — they remain accessible via /mem-recall.

| Variable | Default | Description | |----------|---------|-------------| | CORTEX_STRATEGY | smart | Injection strategy (smart, full, minimal) | | CORTEX_MAX_ENTRIES | 30 | Max entries per file before auto-compact |

Setting environment variables

Windows (PowerShell):

$env:CORTEX_STRATEGY="full"
$env:CORTEX_MAX_ENTRIES="50"
claude

Linux/Mac:

CORTEX_STRATEGY=full CORTEX_MAX_ENTRIES=50 claude

To make it permanent, add to your shell profile (~/.bashrc, ~/.zshrc, or PowerShell $PROFILE).

Cross-Platform Compatibility

Cortex works on Windows, Linux, and macOS.

| Feature | Windows | Linux | macOS | |---------|---------|-------|-------| | install.py | python install.py | python3 install.py | python3 install.py | | install.sh (curl) | Needs Git Bash or WSL | Native | Native | | Hooks | python3 \|\| python fallback | python3 | python3 | | Python detection | python or python3 | python3 | python3 | | Path handling | pathlib (cross-platform) | pathlib | pathlib | | Encoding | UTF-8 forced (fixes cp1252) | Native UTF-8 | Native UTF-8 |

The installer automatically detects the correct Python command and configures hooks with a python3 || python fallback to work on any system.

Gitignore Recommendations

The installer adds these rules automatically:

# Cortex Memory Protocol — personal data
.claude/memory/archive/
.claude/memory/active-context.md
.claude/cortex.json

What to version (shared with your team):

• CLAUDE.md — Protocol rules
• .claude/settings.json — Hook configuration
• .claude/hooks/ — Hook scripts
• .claude/commands/ — Slash commands
• .claude/rules/ — Enforcement rules
• .claude/memory/MEMORY_BANK.md — Project identity
• .claude/memory/decisions.md — Decision log
• .claude/memory/patterns.md — Patterns and gotchas
• .claude/memory/progress.md — Task tracking

What stays local (personal to each dev):

• .claude/memory/active-context.md — Current session state
• .claude/memory/archive/ — Compacted old memories
• .claude/cortex.json — Local installation manifest

Each dev runs /mem-init on first use to create their local files.

Design Philosophy

1. Visibility > Magic

Every memory write generates a visual confirmation: "Registered in decisions.md". You KNOW it's working.

2. Simplicity > Features

Zero external dependencies. Zero servers. Zero databases. Markdown + Python 3.7+ that already exists on your system.

3. Git-native

Memories are .md files. They go in your Git. You can git diff, git log, git blame your memories. Your team shares the MEMORY_BANK.md and decisions.md.

4. Guaranteed Survival

CLAUDE.md survives /compact by Claude Code's design. When context is compacted, Claude re-reads CLAUDE.md from disk. Since the Cortex protocol is there, it resumes immediately.

5. Progressive Disclosure

The SessionStart hook in smart mode (default) injects only the essentials. The full history is available via /mem-recall. Configurable per dev via CORTEX_STRATEGY.

FAQ

Q: How much context do memories consume? A: Depends on strategy. smart (default): ~500 tokens fixed regardless of project size. full: grows over time (~800-2000+). minimal: ~200 tokens. Auto-compact keeps files at max 30 entries (configurable), archiving old ones automatically. Use /mem-status to check current usage.

Q: Does Claude actually follow the write rules? A: Yes, with high adherence. CLAUDE.md + rules + Stop hook (reminder on every response) create 3 layers of enforcement. The visual confirmation gives feedback to the user.

Q: Does it work with subagents/Task? A: Yes. CLAUDE.md is loaded for subagents too. Memories are on disk, accessible by any agent.

Q: Can I use it alongside auto memory or other tools? A: Yes! Cortex is complementary. It handles structured memory (decisions, patterns), while auto memory handles conversational preferences.

Q: What if CLAUDE.md gets too big? A: The Cortex protocol is ~18 lines in CLAUDE.md. Detailed rules live in .claude/rules/memory-protocol.md, loaded on demand via @path. Memory files are injected via the SessionStart hook, not inline in CLAUDE.md.

Q: What happens if I already have hooks in settings.json? A: The installer merges Cortex hooks alongside your existing ones. It never overwrites. Your hooks, plugins, and configuration stay exactly as they are.

Q: How do I update when a new version comes out? A: Run npx cortex-protocol@latest --update /path/to/project. System files get replaced, your memories are preserved.

Q: How do I check if everything is working? A: Run npx cortex-protocol --doctor /path/to/project. It checks all files, hooks, and configuration.

Installer Reference

Usage: npx cortex-protocol [OPTIONS] [TARGET]
   or: python install.py [OPTIONS] [TARGET]

Options:
  --update      Update system files only (preserves memories)
  --uninstall   Remove Cortex (preserves memories)
  --doctor      Check installation health
  --dry-run     Preview changes without writing
  -h, --help    Show help

Examples:
  npx cortex-protocol /path/to/project             # Install
  npx cortex-protocol --update /path/to/project     # Update
  npx cortex-protocol --uninstall /path/to/project  # Uninstall
  npx cortex-protocol --doctor /path/to/project     # Health check
  npx cortex-protocol --dry-run /path/to/project    # Preview

License

MIT — Use, modify, distribute freely.

Built for developers who are tired of repeating themselves.

Zero dependencies. Pure markdown. Infinite memory.