# Cortex — Self-Learning AI Agent
**Cortex** is a self-learning AI agent with persistent memory, tools, plugins, project awareness, and a beautiful terminal UI. Inspired by Claude Code CLI, Gemini CLI, OpenCode, and Hermes.
```bash
# Install from crates.io (requires Rust)
cargo install cortex-agent
# Start using it
cortex
```
## Installation
### 1. Install Rust & Cargo
If you don't have Rust installed, the easiest way is via `rustup`:
```bash
```
Verify it worked:
```bash
rustc --version # Should print rustc 1.70+
cargo --version
```
### 2. Install Cortex
```bash
cargo install cortex-agent
```
This downloads, compiles, and installs the `cortex` binary to `~/.cargo/bin/`.
### 3. Set up an API key
On first run, Cortex creates a template config at `~/.cortex/config.yaml`:
```bash
cortex
```
You'll see a welcome screen with instructions. Set your API key as an environment variable:
```bash
export OPENAI_API_KEY="sk-..."
cortex
```
Or edit `~/.cortex/config.yaml` directly and add your key there.
> **New to AI providers?** Sign up for an API key at one of these:
> - [OpenAI](https://platform.openai.com/api-keys)
> - [OpenRouter](https://openrouter.ai/keys) (multiple models, one key)
> - [DeepSeek](https://platform.deepseek.com/api_keys)
> - [Groq](https://console.groq.com/keys)
> - [Together](https://api.together.ai/settings/api-keys)
> - [Mistral](https://console.mistral.ai/api-keys)
> - [Anthropic](https://console.anthropic.com/keys)
## Features
### 🧠 Memory & Self-Learning
- **Persistent SQLite memory** — facts, preferences, skills, error lessons
- **Auto-categorization** — memories sorted into identity, preference, work, error, api, configuration, code
- **Memory consolidation** — overlapping memories auto-merge with boosted importance
- **Confidence scoring** — access_count tracks recall frequency
- **Memory decay** — old/unused memories degrade and auto-purge
- **Preference learning** — detects "I use X", "I prefer Y" patterns automatically
- **Session summarization** — on exit, Cortex saves a summary with extracted topics
- **Vector/semantic search** — embeddings-based memory retrieval (falls back to keyword)
### 🛠️ CLI Power Features
| `cortex eval "question"` | Non-interactive mode — prints answer and exits |
| `echo "question" \| cortex` | Pipe mode — auto-detects piped input |
| `cortex --doctor` | Full system diagnostics (config, providers, connectivity, memory, plugins) |
| `cortex show` | Display config with API keys masked |
| `cortex get <key>` | Get a config value (e.g., `cortex get active_provider`) |
| `cortex set <key> <value>` | Set a config value (e.g., `cortex set max_tokens 8192`) |
| `cortex validate` | Validate config YAML |
| `cortex context` | Show active project context files (AGENTS.md, CLAUDE.md, .cursorrules) |
| `cortex init` | Create `.cortex/config.yaml` for per-project config |
| `cortex completions bash\|zsh\|fish` | Generate shell completion scripts |
| `cortex doctor` | Same as `--doctor` |
### 🎨 Terminal UI
- **Syntax highlighting** — commands like `/help`, `/memory` highlighted in cyan while typing
- **Ctrl+R** — reverse history search (incremental)
- **Rounded input box** (`╭─ provider/model ──╮`) with turn counter
- **Bordered streaming** — left-wall `│` during response, right-wall `│` on submit
- **Session status bar** — provider, tokens, context %, elapsed, turn count
- **Live token counter** — shows `N tok N/s` during generation
- **Scope indicator** — shows `readonly`/`offline` in status bar when active
- **Time-based greeting** + tip of the day + last session stats on startup
- **Catppuccin-inspired themes** (`/theme mocha` / `/theme latte`)
- **Resize-safe layout** — adapts to terminal width dynamically
### 🔐 Security & Session Control
| `/session readonly` | Block all write/destructive tool operations |
| `/session offline` | Block all network tool operations |
| `/session normal` | Restore full access |
| `/permissions allow <tool>` | Permanently approve a dangerous tool |
| `/permissions list` | Show approved tools |
| `/permissions revoke <tool>` | Revoke approval |
| **API key masking** | Keys auto-redacted in session exports and tool args display |
| **Config auto-backup** | `config.yaml.bak` created before first modification per session |
### 💾 Session Management
| `/session save <name>` | Save current conversation to `~/.cortex/sessions/` |
| `/session load <name>` | Load a saved conversation |
| `/session list` | List saved sessions |
| `/session export` | Export as markdown transcript |
| `/session export --format json` | Export as JSON |
### 📁 Project Intelligence
- **Auto-detects project root** — walks up from cwd looking for AGENTS.md, CLAUDE.md, GEMINI.md, .cursorrules
- **Injects project context** into system prompt automatically
- **Per-project `.cortex/config.yaml`** — settings override global config when inside a project
- **`cortex init`** — creates `.cortex/config.yaml` with auto-detected project type (Rust, Node.js, Python, Java)
- **`cortex context`** — shows what project files are active
### 🛠️ 17+ Built-in Tools (available to the LLM)
| **Web** | `web_search` (DuckDuckGo), `web_fetch` |
| **Code** | `execute_python`, `execute_bash` |
| **Files** | `read_file`, `write_file` |
| **Git** | `git_status`, `git_diff` |
| **Memory** | `save_memory`, `search_memory`, `list_memories`, `forget_memory` |
| **Skills** | `create_skill`, `get_skill`, `update_skill`, `delete_skill`, `list_skills` |
### 🔌 Plugin System
Drop `.yaml` files in `~/.cortex/plugins/` or install from GitHub:
```bash
/plugin install https://github.com/user/repo
/plugin install https://raw.githubusercontent.com/user/repo/main/weather.yaml
/plugin list
```
### 📚 Skill System
Save reusable workflows as versioned skills:
```bash
/skills add # Interactive skill creation (inline prompts)
/skills delete # Remove a skill
/skills # List all skills
```
### 🔄 Provider Support
OpenAI, OpenRouter, DeepSeek, Groq, Together, Mistral, NVIDIA, OpenCode — switch at runtime:
```bash
/provider # Interactive provider/model picker
/switch <name> # Quick provider switch
/provider add # Add a new provider
/provider remove # Remove a provider
/provider test # Test provider connectivity
```
## Quick Start
```bash
# Install
cargo install cortex-agent
# First run — creates config and guides you
cortex
# Inside cortex:
/help # Show all commands
/tools # List available tools
/memory tree # Browse memories by category
/memory stats # Memory statistics
/theme latte # Switch to light theme
/session save work # Save current conversation
/session readonly # Block write operations
/permissions list # Show approved dangerous tools
# From the shell (non-interactive):
cortex eval "What is Rust's ownership model?"
cortex context
cortex get active_provider
cortex completions bash
```
## Commands Reference
| `/help <cmd>` | Categorized help with detailed usage |
| `/tools` | List all available tools grouped by category |
| `/memory` | Browse memories — add `tree`, `timeline`, or `stats` |
| `/skills add\|delete` | Manage reusable skills |
| `/theme mocha\|latte` | Switch between dark/light themes |
| `/plugin list\|install` | Manage plugins |
| `/provider` | Interactive provider/model picker |
| `/provider add\|edit\|remove\|test` | Provider configuration |
| `/switch <name>` | Quick provider switch |
| `/session save\|load\|list\|export` | Session management |
| `/session readonly\|offline\|normal` | Session security scopes |
| `/permissions allow\|list\|revoke` | Tool permission management |
| `/stats` | Session token/cost summary |
| `/model` | Show active provider details |
| `/reset` | Clear conversation |
| `/exit` | Quit and save session |
## Requirements
- **Rust 1.70+** (see [Install Rust & Cargo](#1-install-rust--cargo) above)
- **API key** for any OpenAI-compatible provider (OpenAI, OpenRouter, DeepSeek, etc.)
- **Linux/macOS** terminal (Windows via WSL)
## Updating
```bash
cargo install cortex-agent
```
Cargo will fetch the latest version and rebuild.
## Development
For contributors who want to hack on Cortex itself:
```bash
git clone https://github.com/shafiqul/cortex.git
cd cortex
cargo build --release
./target/release/cortex
```
> **Note:** The `config.yaml` file in the repo root is for local development only and is not shipped in the crates.io package. Use `~/.cortex/config.yaml` for your personal configuration.
## License
MIT
