{"id":35672023,"url":"https://github.com/sopaco/cortex-mem","last_synced_at":"2026-04-25T17:02:27.117Z","repository":{"id":326882543,"uuid":"1107049068","full_name":"sopaco/cortex-mem","owner":"sopaco","description":"🧠 The production-ready memory system for intelligent agents. A complete solution for memory management, from extraction and vector search to automated optimization, with a REST API, MCP, CLI, and insights dashboard out-of-the-box.","archived":false,"fork":false,"pushed_at":"2026-01-11T04:25:53.000Z","size":5240,"stargazers_count":73,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-11T12:04:21.640Z","etag":null,"topics":["agent","cognition","knowledge-base","memories","memory"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sopaco.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-30T13:36:55.000Z","updated_at":"2026-01-11T04:26:00.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/sopaco/cortex-mem","commit_stats":null,"previous_names":["sopaco/cortex-mem"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/sopaco/cortex-mem","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sopaco%2Fcortex-mem","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sopaco%2Fcortex-mem/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sopaco%2Fcortex-mem/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sopaco%2Fcortex-mem/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sopaco","download_url":"https://codeload.github.com/sopaco/cortex-mem/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sopaco%2Fcortex-mem/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28586294,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-19T20:45:59.482Z","status":"ssl_error","status_checked_at":"2026-01-19T20:45:41.500Z","response_time":67,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","cognition","knowledge-base","memories","memory"],"created_at":"2026-01-05T19:01:07.235Z","updated_at":"2026-04-25T17:02:27.096Z","avatar_url":"https://github.com/sopaco.png","language":"Rust","funding_links":["https://github.com/sponsors/sopaco)!"],"categories":["Libraries","Frameworks","Rust","Orchestration \u0026 Workflows","Agentic Systems"],"sub_categories":["Artificial Intelligence"],"readme":"\u003cp align=\"center\"\u003e\n    \u003cimg src=\"./assets/intro/TopBanner.webp\"\u003e\n    \u003cimg src=\"./assets/benchmark/cortex_mem_vs_openclaw_1.png\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"./README.md\"\u003eEnglish\u003c/a\u003e\n    |\n    \u003ca href=\"./README_zh.md\"\u003e中文\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003cstrong\u003e🧠 The AI-native memory framework for building intelligent, context-aware applications 🧠\u003c/strong\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003eBuilt with Rust, Cortex Memory is a high-performance, persistent, and intelligent long-term memory system that gives your AI agents / OpenClaw the ability to remember, learn, and personalize interactions across sessions.\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://github.com/sopaco/cortex-mem/tree/main/litho.docs/en\"\u003e\u003cimg alt=\"Litho Docs\" src=\"https://img.shields.io/badge/Litho-Docs-green?logo=Gitbook\u0026color=%23008a60\"/\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/sopaco/cortex-mem/tree/main/litho.docs/zh\"\u003e\u003cimg alt=\"Litho Docs\" src=\"https://img.shields.io/badge/Litho-中文-green?logo=Gitbook\u0026color=%23008a60\"/\u003e\u003c/a\u003e\n  \u003ca href=\"https://raw.githubusercontent.com/sopaco/cortex-mem/refs/heads/main/assets/benchmark/cortex_mem_vs_openclaw_3.png?raw=true\"\u003e\u003cimg alt=\"Benchmark\" src=\"https://img.shields.io/badge/Benchmark-Perfect-green?logo=speedtest\u0026labelColor=%231150af\u0026color=%2300b89f\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/sopaco/cortex-mem/actions/workflows/rust.yml\"\u003e\u003cimg alt=\"GitHub Actions Workflow Status\" src=\"https://img.shields.io/github/actions/workflow/status/sopaco/cortex-mem/rust.yml?label=Build\"\u003e\u003c/a\u003e\n  \u003ca href=\"./LICENSE\"\u003e\u003cimg alt=\"MIT\" src=\"https://img.shields.io/badge/license-MIT-blue.svg?label=LICENSE\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003chr /\u003e\n\n# 👋 What is Cortex Memory?\n\n**Cortex Memory** is a complete, production-ready framework for giving your AI applications a long-term memory. It moves beyond simple chat history, providing an intelligent memory system with a **hierarchical three-tier memory architecture** (L0 Abstract → L1 Overview → L2 Detail) that automatically extracts, organizes, and optimizes information to make your AI agents smarter and more personalized.\n\nCortex Memory uses a sophisticated pipeline to process and manage memories, centered around a **hybrid storage architecture** combining **virtual-filesystem** durability with vector-based **semantic search**.\n\n| Blazing Fast **Layered Context Loading** | Context Organization as **Virtual Files** |  **Precision** Memory Retrieval |\n| :--- | :--- | :--- |\n| ![Layered Context Loading](./assets/intro/highlight_style_modern.jpg) |![architecture_style_modern](./assets/intro/architecture_style_modern.jpg) | ![architecture_style_classic](./assets/benchmark/cortex_mem_vs_openclaw_2.png) |\n\n**Cortex Memory** organizes data using a **virtual filesystem** approach with the `cortex://` URI scheme:\n\n```\n# Basic Structure\ncortex://{dimension}/{path}\n\n# Dimensions\nsession/    - Session memories (conversation history, timeline)\nuser/       - User memories (preferences, entities, events)\nagent/      - Agent memories (cases, skills)\nresources/  - Knowledge base resources\n\n# Examples\ncortex://session/{session_id}/timeline/{date}/{time}.md\ncortex://user/preferences/{name}.md\ncortex://agent/cases/{case_id}.md\ncortex://resources/{resource_name}/\n```\n\n\u003chr /\u003e\n\n# 😺 Why Use Cortex Memory?\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eTransform your stateless AI into an intelligent, context-aware partner.\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cdiv style=\"text-align: center; margin: 30px 0;\"\u003e\n  \u003ctable style=\"width: 100%; border-collapse: collapse; margin: 0 auto;\"\u003e\n    \u003ctr\u003e\n      \u003cth style=\"width: 50%; padding: 15px; background-color: #f8f9fa; border: 1px solid #e9ecef; text-align: center; font-weight: bold; color: #495057;\"\u003eBefore Cortex Memory\u003c/th\u003e\n      \u003cth style=\"width: 50%; padding: 15px; background-color: #f8f9fa; border: 1px solid #e9ecef; text-align: center; font-weight: bold; color: #495057;\"\u003eAfter Cortex Memory\u003c/th\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd style=\"padding: 15px; border: 1px solid #e9ecef; vertical-align: top;\"\u003e\n        \u003cp style=\"font-size: 14px; color: #6c757d; margin-bottom: 10px;\"\u003e\u003cstrong\u003eStateless AI\u003c/strong\u003e\u003c/p\u003e\n        \u003cul style=\"font-size: 13px; color: #6c757d; line-height: 1.6;\"\u003e\n          \u003cli\u003eForgets user details after every session\u003c/li\u003e\n          \u003cli\u003eLacks personalization and context\u003c/li\u003e\n          \u003cli\u003eRepeats questions and suggestions\u003c/li\u003e\n          \u003cli\u003eLimited to short-term conversation history\u003c/li\u003e\n          \u003cli\u003eFeels robotic and impersonal\u003c/li\u003e\n        \u003c/ul\u003e\n      \u003c/td\u003e\n      \u003ctd style=\"padding: 15px; border: 1px solid #e9ecef; vertical-align: top;\"\u003e\n        \u003cp style=\"font-size: 14px; color: #6c757d; margin-bottom: 10px;\"\u003e\u003cstrong\u003eIntelligent AI with Cortex Memory\u003c/strong\u003e\u003c/p\u003e\n        \u003cul style=\"font-size: 13px; color: #6c757d; line-height: 1.6;\"\u003e\n          \u003cli\u003eRemembers user preferences and history\u003c/li\u003e\n          \u003cli\u003eProvides deeply personalized interactions\u003c/li\u003e\n          \u003cli\u003eLearns and adapts over time\u003c/li\u003e\n          \u003cli\u003eMaintains context across multiple conversations\u003c/li\u003e\n          \u003cli\u003eBuilds rapport and feels like a true assistant\u003c/li\u003e\n        \u003c/ul\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/table\u003e\n\u003c/div\u003e\n\n🌟 \u003cstrong\u003eFor:\u003c/strong\u003e\n- Developers building LLM-powered chatbots and agents.\n- Teams creating personalized AI assistants.\n- Open source projects that need a memory backbone.\n- Anyone who wants to build truly intelligent AI applications!\n\n❤️ Like \u003cstrong\u003eCortex Memory\u003c/strong\u003e? Star it 🌟 or [Sponsor Me](https://github.com/sponsors/sopaco)! ❤️\n\n# 🌠 Features \u0026 Capabilities\n\n- \u003cstrong\u003eFile-System Based Storage:\u003c/strong\u003e Memory content stored as markdown files using the `cortex://` virtual URI scheme, enabling version control compatibility and portability.\n- \u003cstrong\u003eIntelligent Memory Extraction:\u003c/strong\u003e Automatically extracts structured memories (facts, decisions, entities) from conversations using LLM-powered analysis with confidence scoring.\n- \u003cstrong\u003eVector-Based Semantic Search:\u003c/strong\u003e High-performance similarity search via Qdrant with metadata filtering across dimensions (user/agent/session), using weighted scoring.\n- \u003cstrong\u003eMulti-Modal Access:\u003c/strong\u003e Interact through REST API, CLI, MCP protocol, or direct Rust library integration.\n- \u003cstrong\u003eThree-Tier Memory Hierarchy:\u003c/strong\u003e Progressive disclosure system (L0 Abstract → L1 Overview → L2 Detail) optimizes LLM context window usage with lazy generation.\n- \u003cstrong\u003eSession Management:\u003c/strong\u003e Track conversation timelines, participants, and message history with automatic indexing and event-driven processing.\n- \u003cstrong\u003eMulti-Tenancy Support:\u003c/strong\u003e Isolated memory spaces for different users and agents within a single deployment via tenant-aware collection naming.\n- \u003cstrong\u003eEvent-Driven Automation:\u003c/strong\u003e File watchers and auto-indexers for background processing, synchronization, and profile enrichment.\n- \u003cstrong\u003eLLM Result Caching:\u003c/strong\u003e Intelligent caching with LRU eviction and TTL expiration reduces redundant LLM API calls by 50-75%, with cascade layer debouncing for 70-90% reduction in layer updates.\n- \u003cstrong\u003eIncremental Memory Updates:\u003c/strong\u003e Introduced an event-driven incremental update system (`MemoryEventCoordinator`, `CascadeLayerUpdater`) that keeps L0/L1 layers in sync automatically as memories change.\n- \u003cstrong\u003eMemory Forgetting Mechanism:\u003c/strong\u003e Introduced `MemoryCleanupService` based on the Ebbinghaus forgetting curve — automatically archives or deletes low-strength memories to control storage growth in long-running agents.\n- \u003cstrong\u003eAgent Framework Integration:\u003c/strong\u003e Built-in support for Rig framework and Model Context Protocol (MCP).\n- \u003cstrong\u003eWeb Dashboard:\u003c/strong\u003e Svelte 5 SPA (Insights) for monitoring, tenant management, and semantic search visualization.\n\n# 🧠 How It Works\n\nCortex Memory uses a sophisticated pipeline to process and manage memories, centered around a **hybrid storage architecture** combining **virtual-filesystem** durability with vector-based **semantic search**.\n\n```mermaid\nflowchart TB\n    subgraph Input[\"Input Layer\"]\n        User[User Message]\n        Agent[Agent Message]\n        CLI[CLI Commands]\n        API[REST API]\n        MCP[MCP Protocol]\n    end\n\n    subgraph Core[\"Core Engine (cortex-mem-core)\"]\n        Session[Session Manager]\n        Extractor[Memory Extractor]\n        Indexer[Auto Indexer]\n        Search[Vector Search Engine]\n    end\n\n    subgraph Storage[\"Storage Layer\"]\n        FS[(Filesystem\u003cbr/\u003ecortex:// URI)]\n        Qdrant[(Qdrant\u003cbr/\u003eVector Index)]\n    end\n\n    subgraph External[\"External Services\"]\n        LLM[LLM Provider\u003cbr/\u003eExtraction \u0026 Analysis]\n        Embed[Embedding API\u003cbr/\u003eVector Generation]\n    end\n\n    User --\u003e Session\n    Agent --\u003e Session\n    CLI --\u003e Core\n    API --\u003e Core\n    MCP --\u003e Core\n\n    Session --\u003e|Store Messages| FS\n    Session --\u003e|Trigger Extraction| Extractor\n    \n    Extractor --\u003e|Analyze Content| LLM\n    Extractor --\u003e|Store Memories| FS\n    \n    Indexer --\u003e|Watch Changes| FS\n    Indexer --\u003e|Generate Embeddings| Embed\n    Indexer --\u003e|Index Vectors| Qdrant\n    \n    Search --\u003e|Query Embedding| Embed\n    Search --\u003e|Vector Search| Qdrant\n    Search --\u003e|Retrieve Content| FS\n```\n\n## Memory Architecture\n\nCortex Memory organizes data using a **virtual filesystem** approach with the `cortex://` URI scheme:\n\n```\ncortex://{dimension}/{scope}/{category}/{id}\n```\n\n- **Dimension**: `user`, `agent`, `session`, or `resources`\n- **Scope**: Tenant or identifier\n- **Category**: `memories`, `profiles`, `entities`, `sessions`, etc.\n- **ID**: Unique memory identifier\n\n## Three-Tier Memory Hierarchy\n\nCortex Memory implements a **progressive disclosure** system with three abstraction layers:\n\n| Layer | Purpose | Token Usage | Use Case |\n|-------|---------|-------------|----------|\n| **L0 (Abstract)** | Fast positioning, coarse-grained candidate selection | ~100 tokens | Initial screening (20% weight) |\n| **L1 (Overview)** | Structured summary with key points and entities | ~500-2000 tokens | Context refinement (30% weight) |\n| **L2 (Detail)** | Full conversation content | Variable | Precise matching (50% weight) |\n\nThis tiered approach optimizes LLM context window usage by loading only the necessary detail level. The search engine uses **weighted scoring** combining all three layers `L0/L1/L2`.\n\n# 🌐 The Cortex Memory Ecosystem\n\nCortex Memory is a modular system composed of several crates, each with a specific purpose. This design provides flexibility and separation of concerns.\n\n```mermaid\ngraph TD\n    subgraph \"User Interfaces\"\n        CLI[\"cortex-mem-cli\u003cbr/\u003eTerminal Interface\"]\n        Insights[\"cortex-mem-insights\u003cbr/\u003eWeb Dashboard\"]\n    end\n\n    subgraph \"APIs \u0026 Integrations\"\n        Service[\"cortex-mem-service\u003cbr/\u003eREST API Server\"]\n        MCP[\"cortex-mem-mcp\u003cbr/\u003eMCP Server\"]\n        Rig[\"cortex-mem-rig\u003cbr/\u003eRig Framework\"]\n    end\n    \n    subgraph \"Core Engine\"\n        Core[\"cortex-mem-core\u003cbr/\u003eBusiness Logic\"]\n        Tools[\"cortex-mem-tools\u003cbr/\u003eAgent Tools\"]\n    end\n\n    subgraph \"External Services\"\n        VectorDB[(\"Qdrant\u003cbr/\u003eVector Database\")]\n        LLM[(\"LLM Provider\u003cbr/\u003eOpenAI/Azure/Local\")]\n    end\n\n    %% Define Dependencies\n    Insights --\u003e|REST API| Service\n\n    CLI --\u003e Core\n    Service --\u003e Core\n    MCP --\u003e Tools\n    Rig --\u003e Tools\n    Tools --\u003e Core\n    \n    Core --\u003e VectorDB\n    Core --\u003e LLM\n```\n\n- \u003cstrong\u003e`cortex-mem-core`\u003c/strong\u003e: The heart of the system. Contains business logic for filesystem abstraction (`cortex://` URI), LLM client wrappers, embedding generation, Qdrant integration, session management, layer generation (L0/L1/L2), extraction engine, search engine, automation orchestrator, and incremental update system (`MemoryEventCoordinator`, `CascadeLayerUpdater`, `LlmResultCache`, `IncrementalMemoryUpdater`) as well as forgetting mechanism (`MemoryCleanupService`).\n- \u003cstrong\u003e`cortex-mem-service`\u003c/strong\u003e: High-performance REST API server (Axum-based) exposing all memory operations via `/api/v2/*` endpoints. Runs on port 8085 by default.\n- \u003cstrong\u003e`cortex-mem-cli`\u003c/strong\u003e: Command-line tool (`cortex-mem` binary) for developers and administrators to interact with the memory store directly.\n- \u003cstrong\u003e`cortex-mem-insights`\u003c/strong\u003e: Pure frontend Svelte 5 SPA for monitoring, analytics, and memory management through a web interface.\n- \u003cstrong\u003e`cortex-mem-mcp`\u003c/strong\u003e: Model Context Protocol server for integration with AI assistants (Claude Desktop, Cursor, etc.).\n- \u003cstrong\u003e`cortex-mem-rig`\u003c/strong\u003e: Integration layer with the rig-core agent framework for tool registration.\n- \u003cstrong\u003e`cortex-mem-tools`\u003c/strong\u003e: MCP tool schemas and operation wrappers for agent integration.\n- \u003cstrong\u003e`cortex-mem-config`\u003c/strong\u003e: Configuration management module handling TOML loading, environment variable resolution, and tenant-specific overrides.\n\n# 🖼️ Observability Dashboard\n\nCortex Memory includes a powerful web-based dashboard (`cortex-mem-insights`) that provides real-time monitoring, analytics and management capabilities. The dashboard is a pure frontend Svelte 5 SPA that connects to the `cortex-mem-service` REST API.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./assets/snapshots/insights/snapshot_dashboard.png\" alt=\"Cortex Memory Dashboard\" width=\"800\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cem\u003e\u003cstrong\u003eInteractive Dashboard:\u003c/strong\u003e Tenant overview, system health, and storage statistics at a glance\u003c/em\u003e\n\u003c/p\u003e\n\n### Key Features\n\n- **Tenant Management**: View and switch between multiple tenants with isolated memory spaces\n- **Memory Browser**: Navigate the `cortex://` filesystem to view and manage memory files\n- **Semantic Search**: Perform natural language queries across the memory store\n- **Health Monitoring**: Real-time service status and LLM availability checks\n\n### Running the Dashboard\n\n```bash\n# Start the backend service first\ncortex-mem-service --data-dir ./cortex-data --port 8085\n\n# In another terminal, start the insights dashboard\ncd cortex-mem-insights\nbun install\nbun run dev\n```\n\nThe dashboard will be available at `http://localhost:5173` and will proxy API requests to the backend service.\n\n\n# 🦞 Community Showcase: MemClaw\n\n**MemClaw** is a deeply customized memory enhancement plugin for the OpenClaw ecosystem, powered by the locally-running Cortex Memory engine. It delivers superior memory capabilities compared to OpenClaw's built-in memory system, achieving **over 80% token savings** while maintaining exceptional memory accuracy, security, and performance.\n\n## Why MemClaw?\n\n| OpenClaw Native Memory | MemClaw |\n|------------------------|---------|\n| Basic memory storage | **Three-tier L0/L1/L2 architecture** for intelligent retrieval |\n| Higher token consumption | **80%+ token savings** with layered context loading |\n| Limited search precision | **Vector search + Agentic VFS exploration** for complex scenarios |\n\n## Key Features\n\n- **🎯 Low Token \u0026 Hardware Resource Usage**: Rust-powered high-performance memory components with progressive retrieval for optimal context loading\n- **🔒 Complete Data Privacy**: All memories stored locally with zero cloud dependency\n- **🚀 One-Click Migration**: Seamlessly migrate from OpenClaw native memory to MemClaw\n- **⚙️ Easy Configuration**: Zero runtime dependencies, one-line installation, minimal config to get started\n\n## Available Tools\n\n| Tool | Purpose |\n|------|---------|\n| `cortex_search` | Semantic search across all memories with tiered retrieval |\n| `cortex_recall` | Recall memories with extended context (snippet + full content) |\n| `cortex_add_memory` | Store messages for future retrieval |\n| `cortex_close_session` | Close session and trigger memory extraction pipeline |\n| `cortex_migrate` | One-click migration from OpenClaw native memory |\n| `cortex_maintenance` | Periodic maintenance (prune, reindex, layer generation) |\n\n## Quick Start\n\n```bash\n# Install via OpenClaw\nopenclaw plugins install @memclaw/memclaw\n```\n\n\u003e **Note**: Set `memorySearch.enabled: false` to disable OpenClaw's built-in memory and use MemClaw instead.\n\n## Documentation\n\nFor detailed configuration, troubleshooting, and best practices, see the [MemClaw README](examples/@memclaw/plugin/README.md).\n\n---\n\n# 🌟 Community Showcase: Cortex TARS\n\nMeet **Cortex TARS** — a production-ready AI-native TUI (Terminal User Interface) application that demonstrates the true power of Cortex Memory. Built as a \"second brain\" companion, Cortex TARS brings **auditory presence** to your AI experience and can truly hear and remember your voice in the real world, showcases how persistent memory transforms AI interactions from fleeting chats into lasting, intelligent partnerships.\n\n## What Makes Cortex TARS Special?\n\nCortex TARS is more than just a chatbot — it's a comprehensive AI assistant platform that leverages Cortex Memory's advanced capabilities:\n\n### 🎭 Multi-Agent Management\nCreate and manage multiple AI personas, each with distinct personalities, system prompts, and specialized knowledge areas. Whether you need a coding assistant, a creative writing partner, or a productivity coach, Cortex TARS lets you run them all simultaneously with complete separation.\n\n### 💾 Persistent Role Memory\nEvery agent maintains its own long-term memory, learning from interactions over time. Your coding assistant remembers your coding style and preferences; your writing coach adapts to your voice and goals. No more repeating yourself — each agent grows smarter with every conversation.\n\n### 🔒 Memory Isolation\nAdvanced memory architecture ensures complete isolation between agents and users. Each agent's knowledge base is separate, preventing cross-contamination while enabling personalized experiences across different contexts and use cases.\n\n### 🎤 Real-Time Audio-to-Memory (The Game Changer)\n**This is where Cortex TARS truly shines.** With real-time device audio capture, Cortex TARS can listen to your conversations, meetings, or lectures and automatically convert them into structured, searchable memories. Imagine attending a meeting while Cortex TARS silently captures key insights, decisions, and action items — all stored and ready for instant retrieval later. No more frantic note-taking or forgotten details!\n\n## Why Cortex TARS Matters\n\nCortex TARS isn't just an example — it's a fully functional application that demonstrates:\n\n- **Real-world production readiness**: Built with Rust, it's fast, reliable, and memory-safe\n- **Seamless Cortex Memory integration**: Shows best practices for leveraging the memory framework\n- **Practical AI workflows**: From multi-agent conversations to audio capture and memory extraction\n- **User-centric design**: Beautiful TUI interface with intuitive controls and rich features\n\n## Explore Cortex TARS\n\nReady to see Cortex Memory in action? Dive into the Cortex TARS project:\n\n```bash\ncd examples/cortex-mem-tars\ncargo build --release\ncargo run --release\n```\n\nCheck out the [Cortex TARS README](examples/cortex-mem-tars/README.md) for detailed setup instructions, configuration guides, and usage examples.\n\n**Cortex TARS proves that Cortex Memory isn't just a framework — it's the foundation for building intelligent, memory-aware applications that truly understand and remember.**\n\n# 🏆 Benchmark\n\nCortex Memory has been rigorously evaluated on the **LoCoMo10 dataset** (conv-26, 152 questions, 19 conversation sessions spanning May–October 2023) using **LLM-as-a-Judge** — the same methodology used by the OpenViking official evaluation. The results demonstrate Cortex Memory's superior performance against all other systems.\n\n## Performance Comparison\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./assets/benchmark/cortex_mem_vs_openclaw_3.png\" alt=\"Cortex Memory vs OpenViking/OpenClaw's Built-in Memory Benchmark\" width=\"800\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cem\u003e\u003cstrong\u003eOverall Score:\u003c/strong\u003e Cortex Memory v5 achieves \u003cstrong\u003e68.42%\u003c/strong\u003e — outperforming all OpenViking and OpenClaw configurations\u003c/em\u003e\n\u003c/p\u003e\n\n### Overall Scores\n\n| System | Score | Questions |\n|--------|:-----:|:---------:|\n| **Cortex Memory v5 (Intent ON)** | **68.42%** | 152 |\n| OpenViking + OpenClaw (−memory-core) | 52.08% | 1,540 |\n| OpenViking + OpenClaw (+memory-core) | 51.23% | 1,540 |\n| OpenClaw + LanceDB (−memory-core) | 44.55% | 1,540 |\n| OpenClaw (built-in memory) | 35.65% | 1,540 |\n\n### Category Breakdown (v5)\n\n| Category | Description | Score |\n|:--------:|-------------|:-----:|\n| Cat 1 | Factual Recall | 37.50% (12/32) |\n| Cat 2 | Temporal Reasoning | 62.16% (23/37) |\n| Cat 3 | Commonsense Inference | 76.92% (10/13) |\n| Cat 4 | Multi-hop Reasoning | **84.29%** (59/70) |\n| **Total** | | **68.42%** (104/152) |\n\n### Token Efficiency\n\n| System | Avg Tokens / Question | Score | Score per 1K Tokens |\n|--------|:---------------------:|:-----:|:-------------------:|\n| **Cortex Memory v5** | **~2,900** | **68.42%** | **23.6** |\n| OpenViking + OpenClaw (−memory-core) | ~2,769 | 52.08% | 18.8 |\n| OpenViking + OpenClaw (+memory-core) | ~1,363 | 51.23% | 37.6 |\n| OpenClaw (built-in memory) | ~15,982 | 35.65% | 2.2 |\n| OpenClaw + LanceDB (−memory-core) | ~33,490 | 44.55% | 1.3 |\n\n\u003e Cortex Memory achieves **11× fewer tokens** than OpenClaw+LanceDB and **18× better score-per-token** ratio.\n\n### Key Technical Advantages\n\n- **Intent-Driven Retrieval**: Routing multi-hop queries to entity and relational memory scopes improves Cat 4 accuracy by +18.75pp\n- **Hierarchical L0/L1/L2 Architecture**: Precision retrieval starting from ~100-token abstracts — you only pay for context you actually need\n- **Rust-based Implementation**: High-performance, memory-safe core backed by Qdrant vector database\n\n### Evaluation Framework\n\nThe benchmark script is located in `examples/locomo-evaluation`, implementing a two-phase pipeline:\n\n1. **Ingest** — conversation sessions are ingested into Cortex Memory per-sample tenant\n2. **QA** — 152 questions answered via semantic retrieval + LLM generation\n3. **Judge** — LLM-as-a-Judge scores each answer as CORRECT / WRONG (binary, identical to OpenViking methodology)\n\nFor more details on running the evaluation, see the [locomo-evaluation README](examples/locomo-evaluation/README.md) and the full results in [`examples/locomo-evaluation/BENCHMARK.md`](examples/locomo-evaluation/BENCHMARK.md).\n\n# 🖥 Getting Started\n\n### Prerequisites\n- [**Rust**](https://www.rust-lang.org) (version 1.86 or later)\n- [**Qdrant**](https://qdrant.tech/) vector database (version 1.7+)\n- An **OpenAI-compatible** LLM API endpoint (for memory extraction and analysis)\n- An **OpenAI-compatible** Embedding API endpoint (for vector search)\n\n### Installation\nThe simplest way to get started is to use the CLI and Service binaries, which can be installed via `cargo`.\n```sh\n# Install the CLI for command-line management\ncargo install --path cortex-mem-cli\n\n# Install the REST API Service for application integration\ncargo install --path cortex-mem-service\n\n# Install the MCP server for AI assistant integrations\ncargo install --path cortex-mem-mcp\n```\n\n### Configuration\nCortex Memory applications (`cortex-mem-cli`, `cortex-mem-service`, `cortex-mem-mcp`) are configured via a `config.toml` file. The CLI will look for this file in the current directory by default, or you can pass a path using the `-c` or `--config` flag.\n\nHere is a sample `config.toml` with explanations:\n\n```toml\n# -----------------------------------------------------------------------------\n# Qdrant Vector Database Configuration\n# -----------------------------------------------------------------------------\n[qdrant]\nurl = \"http://localhost:6334\"     # URL of your Qdrant instance (gRPC port)\nhttp_url = \"http://localhost:6333\" # HTTP URL for REST API\ncollection_name = \"cortex-memory\"  # Base name for collections (tenant suffix added)\ntimeout_secs = 5                  # Timeout for Qdrant operations\nembedding_dim = 1536              # Embedding dimension (e.g., 1536 for text-embedding-3-small)\n\n# -----------------------------------------------------------------------------\n# LLM (Large Language Model) Configuration (for reasoning, extraction)\n# -----------------------------------------------------------------------------\n[llm]\napi_base_url = \"https://api.openai.com/v1\" # Base URL of your LLM provider\napi_key = \"${OPENAI_API_KEY}\"              # API key (supports env variable)\nmodel_efficient = \"gpt-5-mini\"            # Model for extraction and classification\nmodel_reasoning = \"o1-preview\"             # Model for complex reasoning (optional)\ntemperature = 0.7                          # Sampling temperature for LLM responses\nmax_tokens = 8192                          # Max tokens for LLM generation\ntimeout_secs = 60                           # Timeout for LLM requests\n\n# -----------------------------------------------------------------------------\n# Embedding Service Configuration\n# -----------------------------------------------------------------------------\n[embedding]\napi_base_url = \"https://api.openai.com/v1\" # Base URL of your embedding provider\napi_key = \"${OPENAI_API_KEY}\"              # API key (supports env variable)\nmodel_name = \"text-embedding-3-small\"      # Name of the embedding model to use\nbatch_size = 32                            # Number of texts to embed in a single batch\ntimeout_secs = 30                          # Timeout for embedding requests\n\n# -----------------------------------------------------------------------------\n# Cortex Data Directory Configuration\n# -----------------------------------------------------------------------------\n[cortex]\ndata_dir = \"./cortex-data\"  # Directory for storing memory files and sessions\n```\n\n# 🚀 Usage\n\n### CLI (`cortex-mem-cli`)\n\nThe CLI provides a powerful interface for direct interaction with the memory system. All commands require a `config.toml` file, which can be specified with `--config \u003cpath\u003e`. The `--tenant` flag allows multi-tenant isolation.\n\n#### Add a Memory\nAdds a new message to a session thread, automatically storing it in the memory system.\n\n```sh\ncortex-mem --config config.toml --tenant acme add --thread thread-123 --role user \"The user is interested in Rust programming.\"\n```\n- `--thread \u003cid\u003e`: (Required) The thread/session ID.\n- `--role \u003crole\u003e`: Message role (user/assistant/system). Default: \"user\"\n- `content`: The text content of the message (positional argument).\n\n#### Search for Memories\nPerforms a semantic vector search across the memory store with weighted L0/L1/L2 scoring.\n\n```sh\ncortex-mem --config config.toml --tenant acme search \"what are the user's hobbies?\" --thread thread-123 --limit 10\n```\n- `query`: The natural language query for the search.\n- `--thread \u003cid\u003e`: Filter memories by thread ID.\n- `--limit \u003cn\u003e` / `-n`: Maximum number of results. Default: 10\n- `--min-score \u003cscore\u003e` / `-s`: Minimum relevance score (0.0-1.0). Default: 0.4\n- `--scope \u003cscope\u003e`: Search scope: \"session\", \"user\", or \"agent\". Default: \"session\"\n\n#### List Memories\nRetrieves a list of memories from a specific URI path.\n\n```sh\ncortex-mem --config config.toml --tenant acme list --uri \"cortex://session\" --include-abstracts\n```\n- `--uri \u003cpath\u003e` / `-u`: URI path to list (e.g., \"cortex://session\" or \"cortex://user/preferences\"). Default: `cortex://session`\n- `--include-abstracts`: Include L0 abstracts in results.\n\n#### Get a Specific Memory\nRetrieves a specific memory by its URI.\n\n```sh\ncortex-mem --config config.toml --tenant acme get \"cortex://session/thread-123/memory-456.md\"\n```\n- `uri`: The memory URI.\n- `--abstract-only` / `-a`: Show L0 abstract instead of full content.\n- `--overview` / `-o`: Show L1 overview instead of full content.\n\n#### Delete a Memory\nRemoves a memory from the store by its URI.\n\n```sh\ncortex-mem --config config.toml --tenant acme delete \"cortex://session/thread-123/memory-456.md\"\n```\n\n#### Session Management\nManage conversation sessions.\n\n```sh\n# List all sessions\ncortex-mem --config config.toml --tenant acme session list\n\n# Create a new session\ncortex-mem --config config.toml --tenant acme session create thread-456 --title \"My Session\"\n\n# Close a session (triggers extraction, layer generation, and vector indexing)\ncortex-mem --config config.toml --tenant acme session close thread-456\n```\n\n#### Layers and Stats\nManage layer files and display system statistics.\n\n```sh\n# Display system statistics\ncortex-mem --config config.toml --tenant acme stats\n\n# List available tenants\ncortex-mem --config config.toml tenant list\n\n# Show L0/L1 layer file coverage status\ncortex-mem --config config.toml --tenant acme layers status\n\n# Generate missing L0/L1 layer files\ncortex-mem --config config.toml --tenant acme layers ensure-all\n\n# Regenerate oversized L0 abstract files (\u003e 2K characters)\ncortex-mem --config config.toml --tenant acme layers regenerate-oversized\n```\n\n### REST API (`cortex-mem-service`)\n\nThe REST API allows you to integrate Cortex Memory into any application, regardless of the programming language. The service runs on port 8085 by default.\n\n#### Starting the Service\n```sh\n# Start the API server with default settings (port 8085)\ncortex-mem-service --config config.toml --host 127.0.0.1 --port 8085\n\n# Enable verbose logging\ncortex-mem-service --config config.toml -h 127.0.0.1 -p 8085 --verbose\n```\n\n#### API Endpoints\n\n**Health Check**\n- `GET /health`: Service liveness check\n- `GET /health/ready`: Readiness check (Qdrant, LLM connectivity)\n\n**Filesystem Operations**\n- `GET /api/v2/filesystem/list?uri=\u003cpath\u003e`: List directory contents.\n- `GET /api/v2/filesystem/read/\u003cpath\u003e`: Read file content.\n- `POST /api/v2/filesystem/write`: Write content to a file.\n- `GET /api/v2/filesystem/stats?uri=\u003cpath\u003e`: Get directory statistics.\n\n**Session Management**\n- `GET /api/v2/sessions`: List all sessions.\n- `POST /api/v2/sessions`: Create a new session.\n- `POST /api/v2/sessions/:thread_id/messages`: Add a message to a session.\n- `POST /api/v2/sessions/:thread_id/close`: Close a session and trigger memory extraction.\n\n**Semantic Search**\n- `POST /api/v2/search`: Perform semantic search across memories with weighted L0/L1/L2 scoring.\n\n**Automation**\n- `POST /api/v2/automation/extract/:thread_id`: Trigger memory extraction for a thread.\n- `POST /api/v2/automation/index/:thread_id`: Trigger vector indexing for a thread.\n- `POST /api/v2/automation/index-all`: Index all threads.\n- `POST /api/v2/automation/sync`: Manually trigger synchronization between filesystem and vector store.\n\n**Tenant Management**\n- `GET /api/v2/tenants/tenants`: List all available tenants.\n- `POST /api/v2/tenants/tenants/switch`: Switch active tenant context.\n- `GET /api/v2/tenants/{id}/stats`: Get per-tenant storage metrics.\n\n#### Example: Create a Session and Add Message\n\n```bash\n# Create a new session\ncurl -X POST http://localhost:8085/api/v2/sessions \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"thread_id\": \"thread-123\",\n    \"title\": \"Support Conversation\"\n  }'\n\n# Add a message to the session\ncurl -X POST http://localhost:8085/api/v2/sessions/thread-123/messages \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"role\": \"user\",\n    \"content\": \"I just upgraded to the premium plan.\"\n  }'\n```\n\n#### Example: Semantic Search\n\n```bash\ncurl -X POST http://localhost:8085/api/v2/search \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-Tenant-ID: acme\" \\\n  -d '{\n    \"query\": \"What is the user's current subscription?\",\n    \"thread\": \"thread-123\",\n    \"scope\": \"session\",\n    \"limit\": 5,\n    \"min_score\": 0.5\n  }'\n```\n\n#### Example: Trigger Memory Extraction\n\n```bash\n# Extract memories from a session (typically called when session is closed)\ncurl -X POST http://localhost:8085/api/v2/automation/extract/thread-123 \\\n  -H \"Content-Type: application/json\" \\\n  -d '{ \"auto_save\": true }'\n```\n\n### Model Context Protocol (MCP) Server (`cortex-mem-mcp`)\n\nCortex Memory provides an MCP server for integration with AI assistants like Claude Desktop, Cursor, or GitHub Copilot. The MCP server exposes memory tools through the stdio transport.\n\n```sh\n# Run the MCP server with configuration\ncortex-mem-mcp --config config.toml --tenant acme\n```\n\nThe MCP server exposes the following tools:\n- **store_memory**: Store new facts or conversation summaries\n- **query_memory**: Search memory with natural language\n- **list_memories**: Enumerate available memories by URI prefix\n- **get_memory**: Retrieve a specific memory by URI\n- **delete_memory**: Remove a memory by URI\n\nConfigure your AI assistant to use the MCP server by adding it to your assistant's configuration:\n\n# 🤝 Contribute\nWe welcome all forms of contributions! Report bugs or submit feature requests through [GitHub Issues](https://github.com/sopaco/cortex-mem/issues).\n\n### Development Process\n1. Fork this project\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Create a Pull Request\n\n# 🪪 License\nThis project is licensed under the **MIT License**. See the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsopaco%2Fcortex-mem","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsopaco%2Fcortex-mem","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsopaco%2Fcortex-mem/lists"}