# Delia
MCP server that adds persistent learning and semantic code intelligence to AI coding assistants.
## What It Does
- **Playbooks** - Per-project patterns learned over time, indexed in ChromaDB for semantic retrieval
- **Memories** - Persistent knowledge (markdown), searchable via embeddings
- **Profiles** - Framework-specific guidance, semantically matched to your task
- **Code Index** - Codebase summaries and symbols indexed for intelligent navigation
- **LSP Tools** - Semantic code navigation: find references, go to definition, rename symbols
- **Learning Loop** - Extracts insights from completed tasks and updates playbooks
All knowledge is stored in `.delia/chroma/` for fast semantic search.
**[Full Documentation](docs/README.md)** | [Quick Start](docs/getting-started/quick-start.md) | [Tool Reference](docs/tools/README.md)
## Quick Start
```bash
# 1. Clone and install
git clone https://github.com/zbrdc/delia.git
cd delia
uv sync
# 2. Start HTTP server (recommended for multi-project)
uv run delia run -t http --port 8765
# 3. Initialize your project (from project directory)
cd ~/your-project
uv run --directory ~/git/delia delia init-project
```
## Complete Setup Guide
### Step 1: Install Delia
```bash
git clone https://github.com/zbrdc/delia.git
cd delia
uv sync
```
### Step 2: Configure MCP Clients
Auto-detect and configure all supported AI clients:
```bash
uv run delia install
```
Or install to a specific client:
```bash
uv run delia install claude # Claude Code
uv run delia install cursor # Cursor
uv run delia install vscode # VS Code
```
List available clients:
```bash
uv run delia install --list
```
### Step 3: Start the Server
**Option A: HTTP Transport (Recommended)**
Best for multi-project setups. One server handles all projects.
```bash
uv run delia run -t http --port 8765
```
Add to each project's `.mcp.json`:
```json
{
"mcpServers": {
"delia": {
"type": "http",
"url": "http://localhost:8765/mcp"
}
}
}
```
**Note**: HTTP servers won't appear in Claude Code's `/mcp` list, but tools work normally.
**Option B: stdio Transport**
Per-project server, managed by the AI client. Shows in `/mcp` list.
```json
{
"mcpServers": {
"delia": {
"command": "uv",
"args": ["--directory", "/path/to/delia", "run", "delia", "serve"]
}
}
}
```
### Step 4: Initialize Your Project
**Option A: Via MCP (Recommended)**
Let the AI agent initialize the project - it handles summarization:
```
# In Claude Code or Cursor, just ask:
"Initialize this project with Delia"
# Or use the MCP tool directly:
project(action="init", path="/path/to/your-project")
```
**Option B: Via CLI (requires Ollama)**
If you have Ollama running locally with a model:
```bash
cd ~/your-project
uv run --directory /path/to/delia delia init-project
```
This creates `.delia/` with playbooks tailored to your tech stack.
### Step 5: Verify Setup
```bash
uv run delia doctor
```
## Usage
The AI assistant calls these tools:
```
auto_context("implement user auth") # Load relevant patterns
[work on the task]
complete_task(success=True, bullets_applied=["id1"]) # Record feedback
```
## Project Structure
```
your-project/
├── .delia/
│ ├── chroma/ # Vector database (primary storage)
│ ├── playbooks/ # Learned patterns (JSON, indexed to ChromaDB)
│ ├── memories/ # Persistent knowledge (Markdown, indexed to ChromaDB)
│ └── profiles/ # Framework guides (Markdown, indexed to ChromaDB)
└── CLAUDE.md # Instructions for AI assistants
```
## CLI Commands
```bash
delia run -t http # Start HTTP server (MCP)
delia serve # Start stdio server (MCP)
delia doctor # Health check
delia init-project # Initialize project (requires Ollama)
delia chat # Interactive chat (requires Ollama)
delia agent "task" # Single-shot task (requires Ollama)
```
## Configuration
### Embeddings (for semantic search)
Create `~/.delia/.env`:
```bash
DELIA_VOYAGE_API_KEY=your-key-here
```
Fallback options (no API key needed):
- **Ollama** - Run `ollama pull mxbai-embed-large`
- **Sentence Transformers** - CPU fallback, works offline
### LLM Backends (for CLI features)
For `init-project`, `chat`, `agent` commands, configure backends in `~/.delia/settings.json`:
```json
{
"backends": [{
"name": "ollama-local",
"url": "http://localhost:11434",
"model": "llama3.2"
}]
}
```
## Requirements
- Python 3.11+
- uv (package manager)
- Ollama (optional, for CLI LLM features - not needed if using MCP only)
## License
GPL-3.0
