chandan-cortex 0.1.0

Your personal AI assistant gateway. Simple. Powerful. Local-first. 🧠

🧠 Cortex

Your personal AI assistant gateway. Simple. Powerful. Local-first.

Install · Quick Start · Features · Configuration · Channels · Contributing

---

Cortex is a personal AI assistant you run on your own machine. It comes with a beautiful web dashboard, connects to your messaging channels (Telegram, Discord, Slack), remembers your conversations, and tracks your tasks — all in one pip install.

Why Cortex?
Existing open-source AI assistants are either too complex (24+ channels, 50+ config files, Docker/Tailscale required) or too simple (no memory, no dashboard, no channels). Cortex sits in the sweet spot: powerful enough for real use, simple enough to set up in 60 seconds.

Install

pip install cortex-ai

Or install from source:

git clone https://github.com/chandanhastantram/cortex.git
cd cortex
pip install -e ".[all]"

Quick Start

# 1. Create config (optional — works with env vars too)
cortex init

# 2. Set your API key
export OPENAI_API_KEY="sk-..."
# or: export ANTHROPIC_API_KEY="sk-ant-..."

# 3. Launch
cortex start

Open http://localhost:3100 — that's it! 🚀

Features

🎨 Beautiful Web Dashboard

Premium dark-mode chat UI with glassmorphism design, real-time streaming, conversation management, and markdown rendering.

🧠 Conversation Memory (RAG)

Every conversation is persisted in SQLite. Cortex uses TF-IDF search to recall relevant past conversations when answering new questions — your assistant actually remembers.

🤖 Multi-Model Support

Use any major AI provider with automatic failover:

Provider	Models	How to use
OpenAI	GPT-4o, GPT-4o-mini, GPT-4.5	OPENAI_API_KEY
Anthropic	Claude Opus, Sonnet, Haiku	ANTHROPIC_API_KEY
Ollama	Llama, Mistral, Phi (local)	Set provider to ollama

📬 Messaging Channels

Connect Cortex to your existing chat platforms:

• Telegram — pip install cortex-ai[telegram]
• Discord — pip install cortex-ai[discord]
• Slack — pip install cortex-ai[slack]
• WebChat — Built-in, always available

✅ Task Manager

Built-in task tracking with priorities, tags, and status tracking. Accessible from the dashboard sidebar and the REST API.

📊 Usage Analytics

Track token consumption, API costs, requests per model, and conversation statistics — all in the dashboard.

🔒 Security

• DM pairing policy (like OpenClaw) — unknown senders must be approved
• Auth token support for remote access
• Local-first — all data stays on your machine

🔍 Memory Search

# Search past conversations from CLI
cortex search "python async patterns"

🩺 Health Checks

cortex doctor

Validates your config, dependencies, API keys, and more.

Architecture

Telegram / Discord / Slack / WebChat
        │
        ▼
┌─────────────────────────┐
│       Gateway            │
│   http://127.0.0.1:3100  │
│                          │
│  ┌─────────┐ ┌────────┐ │
│  │ Agent   │ │ Memory │ │
│  │ Runtime │ │ (RAG)  │ │
│  └────┬────┘ └────┬───┘ │
│       │           │      │
│  ┌────▼────┐ ┌────▼───┐ │
│  │ Models  │ │ Tasks  │ │
│  │ OpenAI  │ │ SQLite │ │
│  │ Claude  │ └────────┘ │
│  │ Ollama  │            │
│  └─────────┘            │
└─────────────────────────┘

Configuration

Cortex uses YAML config with sensible defaults. Create one with:

cortex init

Minimal config (~/.cortex/cortex.yaml):

model:
  provider: openai
  model: gpt-4o

memory:
  enabled: true

tasks:
  enabled: true

All settings can be overridden with environment variables:

Env Variable	Config Path
OPENAI_API_KEY	model.api_key
ANTHROPIC_API_KEY	model.api_key
CORTEX_PORT	gateway.port
TELEGRAM_BOT_TOKEN	channels.telegram.token
DISCORD_BOT_TOKEN	channels.discord.token

Channels

Telegram

channels:
  telegram:
    enabled: true
    token: "123456:ABCDEF"  # Or set TELEGRAM_BOT_TOKEN
    dm_policy: pairing

Discord

channels:
  discord:
    enabled: true
    token: "your-bot-token"  # Or set DISCORD_BOT_TOKEN
    dm_policy: pairing

WebChat

Always available at the gateway URL. No additional configuration needed.

CLI Reference

Command	Description
cortex start	Start the gateway server
cortex init	Create example config file
cortex doctor	Run health checks
cortex search "query"	Search conversation memory
cortex stats	Show memory/usage statistics
cortex --version	Show version

API Reference

REST API

Endpoint	Method	Description
GET /api/health	GET	Health check + stats
POST /api/chat	POST	Send a chat message
GET /api/conversations	GET	List conversations
GET /api/conversations/:id/messages	GET	Get messages
DELETE /api/conversations/:id	DELETE	Delete conversation
GET /api/tasks	GET	List tasks
POST /api/tasks	POST	Create task
PATCH /api/tasks/:id	PATCH	Update task
DELETE /api/tasks/:id	DELETE	Delete task
GET /api/memory/search?q=	GET	Search memory
GET /api/usage	GET	Usage statistics

WebSocket

Connect to ws://localhost:3100/ws/chat for real-time streaming chat.

// Send
{"action": "chat", "message": "Hello!", "conversation_id": null}

// Receive (streaming)
{"type": "token", "content": "Hello", "conversation_id": "abc123"}
{"type": "token", "content": "!", "conversation_id": "abc123"}
{"type": "done", "content": "Hello!", "model": "openai/gpt-4o", "latency_ms": 342}

Comparison with OpenClaw

Feature	OpenClaw	Cortex
Install	npm install -g openclaw + onboarding wizard	pip install cortex-ai
Language	TypeScript (monorepo)	Python (single package)
Channels	24+	5 (focused, plugin-based)
Memory/RAG	❌ Session-only	✅ Persistent with RAG search
Web Dashboard	WebChat only	Full dashboard + analytics
Task Manager	❌	✅ Built-in
Usage Analytics	❌	✅ Token costs + model stats
Config	JSON5 (complex)	YAML (simple)
Dependencies	Node 24+, pnpm, Docker	Python 3.10+
Lines of Code	~100K+	~2K

Roadmap

• Slack channel plugin
• WhatsApp (via Baileys bridge)
• Voice input/output (TTS/STT)
• Plugin/skill system
• Scheduled tasks (cron)
• Browser automation tool
• Mobile companion app
• OpenAPI spec generation

Contributing

See CONTRIBUTING.md for guidelines.

AI/vibe-coded PRs welcome! 🤖

License

MIT — free for personal and commercial use.

---

Built with 🧠 by Chandan and the community.