Cortex Memory

Cortex Memory (cortex-mem) is a full-stack AI memory management system designed to provide AI agents with persistent, multi-dimensional context across conversational sessions. It solves the problem of statelessness in AI by automatically capturing, structuring, and retrieving dialogue history using a hierarchical memory model.

Hierarchical Memory Model

The system organizes memory into three semantic layers:

• L0 (Abstract): High-level summaries of conversation intent.
• L1 (Overview): Structured markdown summaries containing key decisions, entities, and outcomes.
• L2 (Detail): Raw, unprocessed conversation transcripts stored as markdown files.

These layers are indexed via vector embeddings and stored in a Qdrant vector database, allowing for fast, context-aware semantic search. The system uses filesystem monitoring to automatically trigger LLM-based summarization and synchronization between the filesystem and the vector store.

Cortex Memory provides a comprehensive suite of features for building intelligent agents:

• File-System Based Storage: Uses the cortex:// URI scheme for markdown-based storage.
• Intelligent Memory Extraction: Uses LLMs to extract structured facts, decisions, and entities with confidence scoring.
• Vector-Based Semantic Search: High-performance similarity search via Qdrant with metadata filtering.
• Multi-Modal Access: Support for REST API, CLI, MCP protocol, and direct Rust library integration.
• Three-Tier Memory Hierarchy: Progressive disclosure (L0/L1/L2) to optimize LLM context windows.
• Session Management: Automatic indexing of conversation timelines and participants.
• Multi-Tenancy: Isolated memory spaces for different users/agents via tenant-aware collection naming.
• Event-Driven Automation: Background processing via file watchers and auto-indexers.
• LLM Result Caching: Reduces API costs by 50-75% using LRU eviction and TTL.
• Memory Forgetting Mechanism: MemoryCleanupService manages storage growth using the Ebbinghaus forgetting curve.
• Integrations: Built-in support for the Rig framework and Model Context Protocol (MCP).

Cortex Memory provides several advanced capabilities for AI application developers:

• File-system based storage: Uses cortex:// URIs to store memory as Markdown files.
• Intelligent Memory Extraction: Uses LLMs to automatically extract structured facts, decisions, and entities from conversations.
• Vector-based Semantic Search: High-performance similarity search via Qdrant with metadata filtering and weighted scoring.
• Multi-modal Access: Interact via REST API, CLI, MCP (Model Context Protocol), or direct Rust library integration.
• Multi-tenant Support: Isolated memory spaces for different users/agents using tenant-aware collection naming.
• Event-driven Automation: Background processing via file monitors and automatic indexers.
• LLM Result Caching: Reduces redundant API calls by 50-75% using LRU eviction and TTL.
• Incremental Updates: Automatically keeps L0/L1 layers synchronized when memory changes.
• Memory Forgetting Mechanism: A MemoryCleanupService based on the Ebbinghaus forgetting curve to archive or delete low-intensity memories and prevent storage bloat.
• Observability: A Svelte 5-based dashboard (Insights) for monitoring and visualizing semantic search.

The following crates define the functional surface of the ecosystem:

• cortex-mem-core: The central engine. Handles cortex:// URI filesystem abstraction, LLM/embedding wrappers, Qdrant integration, session management, the three-tier memory hierarchy (L0/L1/L2), extraction, search, and the MemoryEventCoordinator for incremental updates.
• cortex-mem-service: An Axum-based REST API server. Exposes all memory operations via /api/v2/* endpoints. Default port: 8085.
• cortex-mem-cli: The cortex-mem binary for direct administrative and developer interaction with the memory store.
• cortex-mem-insights: A Svelte 5 SPA for monitoring, analytics, and memory management via a web interface.
• cortex-mem-mcp: A Model Context Protocol server for AI assistants like Claude Desktop or Cursor.
• cortex-mem-rig: Integration layer for the rig-core agent framework.
• cortex-mem-tools: Provides MCP tool schemas and operation wrappers.
• cortex-mem-config: Manages TOML configuration, environment variables, and tenant overrides.

Cortex Memory (cortex-mem) manages AI agent memory through five primary operational workflows. These workflows are structured around a layered retrieval architecture (L0 Abstract, L1 Overview, L2 Detail) and combine vector-based semantic search with filesystem abstraction to ensure persistent, context-aware memory across sessions.

The system's operational landscape is categorized into five workflows:

1. System Initialization (Bootstrap): Occurs per-instance. Handles configuration loading, Dependency Injection (DI) container setup, and service wiring. This is a critical prerequisite for all other workflows.
2. Semantic Memory Search (User-facing): Occurs per-query. Utilizes the vector engine, layer manager, and ranking systems to retrieve memory.
3. Memory Indexing & Sync (Background): Event-driven. Uses file watchers, indexers, and vector stores to keep memory up to date.
4. Memory Extraction & Profiling (Background): Occurs at session-close. Uses LLM extraction, profile merging, and deduplication to refine memory.
5. Multi-Tenant Request Handling (Cross-cutting): Occurs per-request. Manages tenant isolation, URI routing, and collection scoping.