cortex-agent 0.5.0

Self-learning AI agent with persistent memory, tools, plugins, and a beautiful terminal UI
cortex-agent-0.5.0 is not a library.

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.

# 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:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"

Verify it worked:

rustc --version   # Should print rustc 1.70+
cargo --version

2. Install Cortex

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:

cortex

You'll see a welcome screen with instructions. Set your API key as an environment variable:

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:

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

Command What it does
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

Command Description
/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

Command Description
/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)

Category Tools
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:

/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:

/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:

/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

# 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?"
echo "Explain traits" | cortex
cortex doctor
cortex context
cortex get active_provider
cortex completions bash

Commands Reference

Command Description
/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 above)
  • API key for any OpenAI-compatible provider (OpenAI, OpenRouter, DeepSeek, etc.)
  • Linux/macOS terminal (Windows via WSL)

Updating

cargo install cortex-agent

Cargo will fetch the latest version and rebuild.

Development

For contributors who want to hack on Cortex itself:

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