Update DOCKERHUB.md with API flow diagram
This commit is contained in:
Vera-AI
265
DOCKERHUB.md
Normal file
265
DOCKERHUB.md
Normal file
@@ -0,0 +1,265 @@
|
||||
# Vera-AI - Persistent Memory Proxy for Ollama
|
||||
|
||||
**Vera** (Latin): *True* — **True AI Memory**
|
||||
|
||||
---
|
||||
|
||||
## What is Vera-AI?
|
||||
|
||||
Vera-AI is a transparent proxy for Ollama that adds persistent memory using Qdrant vector storage. It sits between your AI client and Ollama, automatically augmenting conversations with relevant context from previous sessions.
|
||||
|
||||
**Every conversation is remembered.**
|
||||
|
||||
---
|
||||
|
||||
## How It Works
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ REQUEST FLOW │
|
||||
└─────────────────────────────────────────────────────────────────────────────────┘
|
||||
|
||||
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
|
||||
│ Client │ ──(1)──▶│ Vera-AI │ ──(3)──▶│ Ollama │ ──(5)──▶│ Response │
|
||||
│ (You) │ │ Proxy │ │ LLM │ │ to User │
|
||||
└──────────┘ └────┬─────┘ └──────────┘ └──────────┘
|
||||
│
|
||||
│ (2) Query semantic memory
|
||||
│
|
||||
▼
|
||||
┌──────────┐
|
||||
│ Qdrant │
|
||||
│ Vector DB│
|
||||
└──────────┘
|
||||
│
|
||||
│ (4) Store conversation turn
|
||||
│
|
||||
▼
|
||||
┌──────────┐
|
||||
│ Memory │
|
||||
│ Storage │
|
||||
└──────────┘
|
||||
|
||||
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ 4-LAYER CONTEXT BUILD │
|
||||
└─────────────────────────────────────────────────────────────────────────────────┘
|
||||
|
||||
Incoming Request (POST /api/chat)
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||||
│ Layer 1: System Prompt │
|
||||
│ • Static context from prompts/systemprompt.md │
|
||||
│ • Preserved unchanged, passed through │
|
||||
└─────────────────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||||
│ Layer 2: Semantic Memory │
|
||||
│ • Query Qdrant with user question │
|
||||
│ • Retrieve curated Q&A pairs by relevance │
|
||||
│ • Limited by semantic_token_budget │
|
||||
└─────────────────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||||
│ Layer 3: Recent Context │
|
||||
│ • Last N conversation turns from Qdrant │
|
||||
│ • Chronological order, recent memories first │
|
||||
│ • Limited by context_token_budget │
|
||||
└─────────────────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||||
│ Layer 4: Current Messages │
|
||||
│ • User message from current request │
|
||||
│ • Passed through unchanged │
|
||||
└─────────────────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
[augmented request] ──▶ Ollama LLM ──▶ Response
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Pull the image
|
||||
docker pull YOUR_USERNAME/vera-ai:latest
|
||||
|
||||
# Create directories
|
||||
mkdir -p config prompts logs
|
||||
|
||||
# Create environment file
|
||||
cat > .env << EOF
|
||||
APP_UID=$(id -u)
|
||||
APP_GID=$(id -g)
|
||||
TZ=America/Chicago
|
||||
EOF
|
||||
|
||||
# Run
|
||||
docker run -d \
|
||||
--name vera-ai \
|
||||
--env-file .env \
|
||||
-v ./config/config.toml:/app/config/config.toml:ro \
|
||||
-v ./prompts:/app/prompts:rw \
|
||||
-v ./logs:/app/logs:rw \
|
||||
--network host \
|
||||
YOUR_USERNAME/vera-ai:latest
|
||||
|
||||
# Test
|
||||
curl http://localhost:11434/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Features
|
||||
|
||||
| Feature | Description |
|
||||
|---------|-------------|
|
||||
| 🧠 **Persistent Memory** | Conversations stored in Qdrant, retrieved contextually |
|
||||
| 📅 **Monthly Curation** | Daily + monthly cleanup of raw memories |
|
||||
| 🔍 **4-Layer Context** | System + semantic + recent + current messages |
|
||||
| 👤 **Configurable UID/GID** | Match container user to host for permissions |
|
||||
| 🌍 **Timezone Support** | Scheduler runs in your local timezone |
|
||||
| 📝 **Debug Logging** | Optional logs written to configurable directory |
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
### Environment Variables
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `APP_UID` | `999` | Container user ID (match your host UID) |
|
||||
| `APP_GID` | `999` | Container group ID (match your host GID) |
|
||||
| `TZ` | `UTC` | Container timezone |
|
||||
| `VERA_CONFIG_DIR` | `/app/config` | Config directory |
|
||||
| `VERA_PROMPTS_DIR` | `/app/prompts` | Prompts directory |
|
||||
| `VERA_LOG_DIR` | `/app/logs` | Debug logs directory |
|
||||
|
||||
### Required Services
|
||||
|
||||
- **Ollama**: LLM inference server
|
||||
- **Qdrant**: Vector database for memory storage
|
||||
|
||||
### Example config.toml
|
||||
|
||||
```toml
|
||||
[general]
|
||||
ollama_host = "http://YOUR_OLLAMA_IP:11434"
|
||||
qdrant_host = "http://YOUR_QDRANT_IP:6333"
|
||||
qdrant_collection = "memories"
|
||||
embedding_model = "snowflake-arctic-embed2"
|
||||
debug = false
|
||||
|
||||
[layers]
|
||||
semantic_token_budget = 25000
|
||||
context_token_budget = 22000
|
||||
semantic_search_turns = 2
|
||||
semantic_score_threshold = 0.6
|
||||
|
||||
[curator]
|
||||
run_time = "02:00" # Daily curator
|
||||
full_run_time = "03:00" # Monthly curator
|
||||
full_run_day = 1 # Day of month (1st)
|
||||
curator_model = "gpt-oss:120b"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Docker Compose
|
||||
|
||||
```yaml
|
||||
services:
|
||||
vera-ai:
|
||||
image: YOUR_USERNAME/vera-ai:latest
|
||||
container_name: vera-ai
|
||||
env_file:
|
||||
- .env
|
||||
volumes:
|
||||
- ./config/config.toml:/app/config/config.toml:ro
|
||||
- ./prompts:/app/prompts:rw
|
||||
- ./logs:/app/logs:rw
|
||||
network_mode: "host"
|
||||
restart: unless-stopped
|
||||
healthcheck:
|
||||
test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:11434/')"]
|
||||
interval: 30s
|
||||
timeout: 10s
|
||||
retries: 3
|
||||
start_period: 10s
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Memory System
|
||||
|
||||
### 4-Layer Context
|
||||
|
||||
1. **System Prompt** - From `prompts/systemprompt.md`
|
||||
2. **Semantic Memory** - Curated Q&A retrieved by relevance
|
||||
3. **Recent Context** - Last N conversation turns
|
||||
4. **Current Messages** - User/assistant from request
|
||||
|
||||
### Curation Schedule
|
||||
|
||||
| Schedule | Time | What |
|
||||
|----------|------|------|
|
||||
| Daily | 02:00 | Recent 24h raw memories |
|
||||
| Monthly | 03:00 on 1st | ALL raw memories |
|
||||
|
||||
---
|
||||
|
||||
## API Endpoints
|
||||
|
||||
| Endpoint | Method | Description |
|
||||
|----------|--------|-------------|
|
||||
| `/` | `GET` | Health check |
|
||||
| `/api/chat` | `POST` | Chat completion (with memory) |
|
||||
| `/api/tags` | `GET` | List models |
|
||||
| `/curator/run` | `POST` | Trigger curator |
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Permission Denied
|
||||
|
||||
```bash
|
||||
# Get your UID/GID
|
||||
id
|
||||
|
||||
# Set in .env
|
||||
APP_UID=1000
|
||||
APP_GID=1000
|
||||
|
||||
# Rebuild
|
||||
docker compose build --no-cache
|
||||
```
|
||||
|
||||
### Wrong Timezone
|
||||
|
||||
```bash
|
||||
# Set in .env
|
||||
TZ=America/Chicago
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Source Code
|
||||
|
||||
- **Gitea**: http://10.0.0.61:3000/SpeedyFoxAi/vera-ai-v2
|
||||
|
||||
---
|
||||
|
||||
## License
|
||||
|
||||
MIT License
|
||||
|
||||
---
|
||||
|
||||
Brought to you by SpeedyFoxAi
|
||||
Reference in New Issue
Block a user