Cortex-agents_infra

[English Version Available](README.en.md) # Cortex Agent Infrastructure (`.cortex`) **"The Bridge between Human Intent and Agent Intelligence."** A universal agent engineering infrastructure designed to persist the memories of fragmented agents and form an immediate working context in any project through the Model Context Protocol (MCP). It combines the latest multi-agent orchestration patterns and hybrid database technologies to provide a local-first context engine. The recent structure uses the `.cortex` path model, with MCP, watcher, process control, and runtime router separated into Rust crates. ## System Architecture The existing Python monolithic engine has been separated into Rust MCP dispatcher, Rust engine server, Rust watcher, Rust process control layers, and Python worker/helper layers. `cortex`, `cortex-engine`, `cortex-mcp`, and `cortex-watcher` are responsible for the operational surface, while Python handles heavy native package interactions, such as embedding workers and Kuzu graph helpers. ```mermaid --- config: flowchart: curve: stepAfter nodeSpacing: 50 rankSpacing: 80 --- flowchart TB subgraph RequestFlow["Request / Retrieval Flow"] direction LR Agent["Coding Agent / IDE"] subgraph MCP["MCP Layer"] direction TB Entry["MCP Entry Point<br/>Request Reception · Response Return"] Router["Request Router<br/>Input Validation · Function Routing"] Handler["Capability Handlers<br/>Search · Memory · Indexing · Editing · Session"] end subgraph Retrieval["Retrieval Layer"] direction TB Plan["Query Planning<br/>Scope · Filter · Intent Organization"] Search["Hybrid Retrieval<br/>Keyword + Vector + Structural Exploration"] Format["Rank & Format<br/>Candidate Merging · Ranking · Location Inclusion"] end Agent -->|"tool request"| Entry Entry -->|"validated request"| Router Router -->|"capability request"| Handler Handler -->|"search request"| Plan Plan -->|"planned query"| Search Search -->|"candidate context"| Format Format -->|"ranked context"| Handler Handler -->|"tool result"| Agent end subgraph IndexFlow["Indexing / Write Flow"] direction LR Local["Local CLI / File Watcher"] subgraph Pipeline["Indexing Pipeline"] direction TB FileSelect["File Selection<br/>Target File Exploration · Change File Selection"] Extract["Parse & Extract<br/>Symbol · Reference · Call Relationship Extraction"] Chunk["Chunk & Metadata<br/>Search Unit · Line Range · Context Creation"] GraphSync["Graph Sync<br/>Code Structure Graph Reflection"] end subgraph Runtime["Runtime Layer"] direction TB RuntimeService["Runtime Service<br/>Long-Running Process · Job Relay"] EmbeddingWorker["Embedding Worker<br/>Text Embedding Generation"] end Local -->|"manual index / file change"| FileSelect Handler -->|"index command / workspace scope"| FileSelect FileSelect -->|"selected files"| Extract Extract -->|"symbols / references / call relations"| Chunk Extract -->|"graph facts"| GraphSync Chunk -->|"texts to embed"| RuntimeService RuntimeService -->|"embedding job"| EmbeddingWorker EmbeddingWorker -->|"vectors"| RuntimeService RuntimeService -->|"vector result"| Chunk end subgraph Storage["Persistent Storage"] direction LR SQLVector[("Physical Store 1<br/>SQLite + Text Index + Vector<br/>File · Chunk · Memory · Symbol · Edge · Vector")] GraphDB[("Physical Store 2<br/>Kuzu Graph Store<br/>Code Graph Node · Relationship")] end Search -->|"keyword / vector / metadata lookup"| SQLVector SQLVector -->|"candidate rows / matches"| Search Search -->|"related structure lookup"| GraphDB GraphDB -->|"related nodes / relations"| Search Chunk -->|"chunks / metadata / vectors"| SQLVector Extract -->|"symbol rows / edge rows"| SQLVector GraphSync -->|"graph nodes / graph relations"| GraphDB %% Input / Request / Write Flow linkStyle 0,1,2,3,4,5,8,9,10,11,12,13,14,17,19,21,22,23 stroke:#2563eb,stroke-width:2px; %% Result / Response Flow linkStyle 6,7,15,16,18,20 stroke:#16a34a,stroke-width:2px; style RequestFlow fill:#f8fafc,stroke:#cbd5e1 style IndexFlow fill:#f8fafc,stroke:#cbd5e1 style Storage fill:#f8fafc,stroke:#cbd5e1 ``` ## Key Features ### 1. Hybrid Context Engine & AST Parsing - **AST Structural Parsing (`Tree-sitter`)**: Analyzes code from languages like Python, C#, and TypeScript at the AST level to extract class, function, and call relationships. - **Vector Search (`sqlite-vec`)**: Performs semantic search locally using SQLite-based vector search without an external server. - **Graph Analysis (`Kuzu DB`)**: Tracks function calls, inclusion relationships, and external references in graph form. - **FTS5 Text Search**: Supports keyword-based search combined with Reciprocal Rank Fusion (RRF). ### 2. Runtime Modularization The runtime control layer is separated as follows: - `rust/crates/ctl`: Start/status/stop orchestration and process path management - `rust/crates/runtime`: Rust engine router, worker supervisor, idle monitor, and length-prefixed JSON IPC - `rust/crates/watcher`: File watch, scan, parse, and SQLite write path - `src/cortex/runtime/engine_worker.py`: PyTorch/SentenceTransformers embedding worker Python remains in areas like embedding model ecosystem worker/provider, Kuzu graph helper, and parser helper, while runtime orchestration and MCP operate based on Rust binaries. ### 3. `.cortex` Path Model Separates the Cortex installation location from the working project data location. - `CORTEX_HOME`: Cortex root directory (where `pyproject.toml` is located) - `CORTEX_WORKSPACE`: Actual working project root directory - `CORTEX_DATA_HOME`: Database/index root directory (defaults to `~/.cortex`) - `CORTEX_WORKSPACE_KEY`: Multi-repo grouping — specify the same value to group multiple folders into one workspace - `CORTEX_ENV_PATH`: Used to specify the location of the `.env` file directly - `CORTEX_START_TIMEOUT`: Time (in seconds) for `cortex start` to wait for the engine to be ready (default 35, recommended 60~120 for WSL/CUDA) Code index (`memories.db`, `graph_db_store/`) and history are generated under `~/.cortex/workspaces/<workspace-key>/` by default. Specifying `CORTEX_DATA_HOME` allows for a different global data root. Cortex updates are performed in the user-specified installation folder. ### 4. Multi-Lane Parallel Execution A domain (lane)-based parallel lock system reduces conflicts when multiple terminals or agents work simultaneously. The relay layer handles job handoff and concurrency control. ### 5. Hardware-Aware Embedding Strategy Isolates the SentenceTransformers/PyTorch-based embedding worker into a separate process. GPU/MPS/CUDA usage is left to the Python worker, while the control/server/router layer maintains a model-agnostic structure. ## Directory Structure ```text .cortex/ # Cortex core ├── docs/ # Infrastructure documentation ├── hooks/ # Runtime lifecycle hooks ├── rules/ # Agent behavior rules and precise editing guidelines ├── scripts/ # Cortex core modules, MCP server, and runtime control layers ├── tasks/ # Active tracking task documents ├── templates/ # System templates and ignore bundles ├── knowledge/ │ └── knowledge.zip # External knowledge seed (optional deployment) ├── pyproject.toml # uv-based dependency declaration ├── .venv/ # [non-shared] uv virtual environment ├── uv.lock # Package lock file └── settings.yaml # Infrastructure global settings ~/.cortex/ # Global data root (CORTEX_DATA_HOME) └── workspaces/ └── <sha1-of-workspace-path>/ # Workspace isolation ├── memories.db # Memory · observation · session (sqlite + vec) ├── graph_db_store/ # Code graph (kuzu) └── history/ # Session logs · observation history ``` ## Cortex Modular Layout Following recent structural reforms, the Cortex backend has been separated into Rust crate-centric components. SQLite, search, memory, editing, and watcher control are handled in Rust, while Python maintains embedding workers/providers, Kuzu graph helpers, and parser helpers: - `rust/crates/mcp`: MCP JSON-RPC tool catalog, search, memory, editing, and session tools - `rust/crates/storage`: SQLite schema, resolver, common storage access, and Python Kuzu bridge - `rust/crates/scanner`: `.gitignore`-based file exploration and filtering - `rust/crates/parsers`: Python parser helper bridge and common JSON schema types - `rust/crates/watcher`: File watch, scan, parse, and SQLite write path - `rust/crates/runtime`: Daemon router, worker supervisor, IPC, and execution environment infrastructure - `src/cortex/embeddings`, `src/cortex/runtime/engine_worker.py`: PyTorch/SentenceTransformers model loading and inference - `src/cortex/storage/graph.py`: Python Kuzu sync/query helper - `src/cortex/parsers`: Python parser helper and language-specific parser implementation > External Workspace path mapping follows the Rust `cortex`/`cortex-engine` path policy, and model download or GPU token dependency verification is excluded from the default CI and classified as a separate verification target after local configuration. ## Installation and Usage Refer to [INSTALL.md](./INSTALL.md) for detailed installation instructions. - Installation on WSL: Follow the `Installation on WSL / Linux` section in [INSTALL.md](./INSTALL.md) from top to bottom. - Installation on Windows: Follow the `Installation on Windows PowerShell` section in [INSTALL.md](./INSTALL.md) from top to bottom. Installation flow summary: - Clone and build the Cortex core in the user-specified tool installation folder. - Add the `cortex` executable path to the PATH. - Run `cortex status` in the actual working project. - Project data is generated under `~/.cortex/workspaces/<workspace-key>/` by default. Embedding is a core feature of Cortex. The default model `Qwen/Qwen3-Embedding-0.6B` is downloaded to the HuggingFace cache during the first execution. No token is required when using public models. GPU acceleration is optional. Follow the GPU acceleration section in [INSTALL.md](./INSTALL.md) only when using the bf16/Flash-Attention path on Ampere or higher GPUs, such as NVIDIA RTX 3000 series. ### cortex Command Surface ```text cortex start | stop | restart | status # MCP engine lifecycle cortex relay acquire | release | status | force-release ``` ```text cortex index | index scan | index roots | index add <path> | index remove <target> | index file <path> ``` ### MCP Registration MCP registration is based on the built Rust `cortex-mcp` binary. Specify `CORTEX_WORKSPACE`, `CORTEX_DATA_HOME`, and `CORTEX_WORKSPACE_KEY` if necessary, to ensure platform-specific data paths are separated. ```powershell $CORTEX_WORKSPACE = (Resolve-Path ..\your-project).Path gemini mcp add -s user ` -e CORTEX_WORKSPACE="$CORTEX_WORKSPACE" ` -e CORTEX_DATA_HOME="$env:USERPROFILE\.cortex" ` cortex-mcp -- "$env:LOCALAPPDATA/Cortex/rust/target/release/cortex-mcp.exe" ``` ## CI Verification Scope GitHub Actions verifies the following on Windows and Ubuntu: - Dependency installation based on `uv sync --group dev` - Rust workspace build/test - Embedding worker/provider import smoke - Maintaining Python tests - `.cortex` based test workspace indexing - Rust MCP JSON-RPC smoke test Long-running daemon practical operation, actual GPU/CUDA memory operation, and local model cache status are environment-dependent and are subject to local verification. The verification procedure follows [local verification procedure in INSTALL.md](./INSTALL.md#local-verification-procedure). ## Inspiration and References - **Vexp**: Universal workflow framework structure and DB schema format reference - **oh-my-agent**: Role-based agent specialization and portable agent definition concept - **oh-my-claudecode**: In-depth interview and artifact-based handoff pattern - **oh-my-openagent**: Hash-based precision editing and verification loop pattern ## License - **Code**: [MIT License](LICENSE) - **Knowledge**: The original external knowledge library is [antigravity-awesome-skills](https://github.com/sickn33/antigravity-awesome-skills) and follows the [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) license.