cortex-os

# Cortex OS [](https://www.python.org/) [](LICENSE) Equip AI Agents with long-term memory and cognitive abilities, enabling them to remember, recall, learn, and evolve. ## Do Your AI Tools Have These Issues? * **Forgetfulness in conversations**: Yesterday's conversation is lost in a new chat. The AI searches from scratch every time. * **Multiple AI tools with isolated memories**: One tool doesn't know what the other said or did. * **Complex tasks get messy**: Multi-step tasks get lost, and the AI forgets important details. * **Teaching the same thing over and over**: Every tool needs to be taught separately. * **Preferences aren't remembered**: Saying "I prefer React over Vue" multiple times doesn't help. ## What Cortex OS Does * **Remember all conversations, forever**: Automatically capture key information and recall it next time. * **Shared memory across tools**: Claude, Codex, and Hermes share the same memory. * **Skill fusion and evolution**: Import, merge, and evolve skills across tools. * **Automatic habit learning**: Learn preferences and adapt to user behavior. * **Context management for long tasks**: Keep track of multi-step tasks and their status. ## Comparison | | Without Cortex OS | With Cortex OS | | --- | --- | --- | | Conversation Memory | Starts from scratch | Automatically recalls history | | Multi-Agent | Isolated information | Shared memory | | Complex Tasks | Gets lost or forgotten | Tracks progress, allows rollback | | Context Management | Window gets bloated | Three-stage assembly, stays compact | | Preference Learning | Needs constant correction | Automatically refines, gets smarter | | Skills | Each tool has its own, no sharing | Cross-tool import, conflict detection, evolution | ## Quick Start ```bash pip install cortex-os ``` ```python from core import MemoryService ms = MemoryService("store.db") ms.record("I use RTX 5060, 8GB memory") ms.recall("RTX") # → ["[Memory] I use RTX 5060, 8GB memory"] ``` **Multi-step tasks:** ```python ms.init_session("process", initial_step="identity_verification") ms.update_state("process", fields={"name": "John", "id": "123456"}) ms.update_state("process", step="material_upload", add_actions=["need to upload ID photo"]) ctx = ms.assemble_context("process", "upload_material") # Agent receives complete context: current step, what's needed ``` ## Installation ```bash pip install cortex-os # Core engine, zero external dependencies pip install cortex-os[mcp] # Includes MCP Server ``` ## Start ```bash python -m adapters.mcp_server # stdio mode python -m adapters.mcp_server --transport http # HTTP mode ``` Docker also works: ```bash docker compose --profile core up memory-service -d ``` ## Connect to Agent After starting, tell your AI tool to connect to `http://localhost:8765/sse`. MCP configuration template is in `adapters/mcp.json`. **Or copy this to your Agent:** > Help me connect to Cortex OS's memory service. This is an MCP Server at http://localhost:8765/sse, with configuration template in adapters/mcp.json. Please set it up according to this format. ## Configuration (optional) ```yaml llm_endpoint: https://api.openai.com/v1/chat/completions llm_model: gpt-4o llm_api_key: sk-xxx embedding_endpoint: http://localhost:8080/v1/embeddings embedding_model: bge-large-zh-v1.5 ``` ## API Overview | What you can do | Method | | --- | --- | | Record conversation | `record(text)` | | Search memory | `recall(query)` | | Assemble context | `assemble_context(session, query)` | | Track task progress | `init_session(id)` `update_state(...)` `rollback_state(id)` | | Import history | `import_history(id, messages)` | | Manage skills | `skill_add(name, desc)` `skill_list()` `skill_merge(ids)` | | Import Agent Skill | `skill_import_claude(dir)` `skill_import_codex(path)` `skill_import_hermes(dir)` | | View knowledge graph | `export_graph_html(path)` | | Export notes | `export_markdown(dir)` | All MCP tools (18) are available in the `adapters/` directory. ## Project Structure ``` core/ 14 modules: memory / recall / consolidate / state / context / skills / visualization adapters/ MCP Server + Agent configuration templates tests/ 156 tests covering all functionality ``` Zero external dependencies, runs on Python standard library.