cortex-recall 0.5.0

Four-layer cognitive memory for AI agents — persistent recall, semantic search, knowledge graph, and learned evolution. No API key required.

cortex-ai

Four-layer cognitive memory for AI agents. Persistent recall across sessions, semantic search, a knowledge graph, and a learning system that evolves from your corrections. No API key required — runs locally on CPU.

pip install cortex-recall
cortex init

---

What it does

AI agents have amnesia. Every new conversation starts blank. cortex-ai gives them memory that works like a brain — organized, searchable, and self-maintaining.

Layer	Name	What it does
L1	Identity	Who the agent is, rules, personality (always loaded)
L2	Recall	72h deterministic short-term log + semantic search across history (on demand)
L3	Knowledge	External docs, vendor manuals, reference material (RAG)
L4	Evolution	Learns from corrections, promotes patterns to permanent rules
L5	Pattern Detection	Clusters correction events using sentence-transformers, auto-promotes to feedback files

Plus Dream (Default Mode Network): background maintenance that prunes the 72h log, consolidates memories, applies half-life decay, and runs L5 pattern clustering. Runs on cron. Zero token cost.

---

How it works

cortex-ai stores memories in a local "palace" — a ChromaDB vector store plus a SQLite knowledge graph. Memories are organized into wings (top-level topics) and rooms (aspects within a topic), then auto-classified by content. Search is semantic, not keyword: ask the meaning of a thing and get matches even if the words don't line up.

The architecture is designed around how the human brain actually organizes memory — separate systems for identity, episodic recall, semantic knowledge, and procedural learning. You can read each layer independently, or combine them via the unified search interface.

---

Quickstart

# Install
pip install cortex-recall

# One-time setup (creates ~/.cortex/ palace)
cortex init

# Mine an existing project directory into memories
cortex mine /path/to/project

# Search semantically
cortex search "how did we handle authentication?"

# See palace status
cortex status

---

MCP server (for Claude Code, etc.)

cortex-ai ships an MCP (Model Context Protocol) server so AI agents can query the palace as a tool:

# Register with Claude Code
claude mcp add cortex -s user -- python -m cortex.mcp_server

Available tools:

• cortex_search — semantic search across all memories
• cortex_status — palace overview
• cortex_list_wings — top-level topics
• cortex_list_rooms — aspects within a wing
• cortex_get_taxonomy — full wing → room tree
• cortex_check_duplicate — avoid filing the same memory twice
• cortex_add — file a new memory
• cortex_kg_add — add a fact to the knowledge graph
• cortex_kg_query — query relationships
• cortex_stm_log — log an event to the 72h short-term memory
• cortex_stm_fetch — fetch and filter the 72h event log
• cortex_dream_run — run full nightly maintenance sweep
• cortex_dream_consolidate — deduplicate and compact palace memories
• cortex_dream_decay — apply half-life decay to memories
• cortex_dream_patterns — L5 pattern detection and promotion

---

Tech stack

• Python 3.9+
• ChromaDB — vector embeddings, semantic search, local-first
• SQLite — knowledge graph with temporal triples
• sentence-transformers — all-MiniLM-L6-v2 (runs on CPU, ~80MB model)
• No external APIs — everything runs on your machine

---

License & attribution

MIT License. See LICENSE and NOTICE.

cortex-ai is a fork of MemPalace by milla-jovovich. The MemPalace engine — ChromaDB-backed search, knowledge graph, palace structure, miner system — is the foundation. cortex-ai adds the four-layer cognitive architecture, MCP server interface, hooks integration, and onboarding flow on top.

---

Status

cortex-ai v0.5.0 is in beta. Issues welcome at https://github.com/jdomian/cortex-ai/issues.