kv-ai/USER_MANUAL.md

Companion AI - User Manual

A practical guide to running and using your personal AI companion.

---

Quick Start (5 minutes)

Option 1: Docker (Recommended)

# 1. Clone and enter directory
git clone https://github.com/santhoshjan/companion.git
cd companion

# 2. Edit config.json - set your vault path
nano config.json
# Change: "path": "/home/yourname/KnowledgeVault/Default"

# 3. Start everything
docker-compose up -d

# 4. Open the UI
open http://localhost:5173

Option 2: Manual Install

# Install dependencies
pip install -e ".[dev]"

# Run the API
python -m uvicorn companion.api:app --host 0.0.0.0 --port 7373

---

Configuration

Before first use, edit config.json:

{
  "vault": {
    "path": "/path/to/your/obsidian/vault"
  }
}

Required paths to set:

• vault.path - Your Obsidian vault directory
• rag.vector_store.path - Where to store embeddings (default: ~/.companion/vectors)
• companion.memory.persistent_store - Conversation history (default: ~/.companion/memory.db)

---

Indexing Your Vault

The system needs to index your vault before it can answer questions.

One-time Full Index

# Using Python module
python -m companion.indexer_daemon.cli index

# Or with Docker
docker-compose exec companion-api python -m companion.indexer_daemon.cli index

Output:

Running full index...
Done. Total chunks: 12,847

Continuous File Watching

# Auto-sync when files change
python -m companion.indexer_daemon.watcher

What it does:

• Monitors your vault for changes
• Automatically re-indexes modified files
• Debounced (5-second delay to batch rapid changes)

Check Index Status

python -m companion.indexer_daemon.cli status

Output:

Total chunks: 12,847
Indexed files: 847
Unindexed files: 3

Incremental Sync

# Sync only changed files
python -m companion.indexer_daemon.cli sync

When to use:

• After editing a few notes
• Faster than full re-index
• Keeps vector store updated

---

Using the Chat Interface

Web UI

1. Start the backend: python -m uvicorn companion.api:app --port 7373
2. In another terminal: cd ui && npm run dev
3. Open http://localhost:5173

Interface:

• Type messages in the bottom textarea
• Press Enter to send
• Citations appear in a side panel when RAG retrieves context
• Conversation history persists per session

API Directly

# Start a conversation
curl -X POST http://localhost:7373/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What did I write about my trip to Japan?",
    "stream": true
  }'

Parameters:

• message (required): Your question
• session_id (optional): Continue existing conversation
• stream (optional): Stream response (default: true)
• use_rag (optional): Enable vault search (default: true)

Get Session History

curl http://localhost:7373/sessions/{session_id}/history

---

Fine-Tuning (Optional)

Extract Training Data

# Extract reflection examples from your vault
python -m companion.forge.extract \
  --output training_data.jsonl \
  --min-length 100

Train Model

# Start training (takes hours, needs GPU)
python -m companion.forge.train \
  --data training_data.jsonl \
  --output-dir ./models

Export to GGUF

# Convert for llama.cpp inference
python -m companion.forge.export \
  --model ./models/checkpoint \
  --output companion-7b.gguf

Reload Model (Hot Swap)

# Admin endpoint - reload without restarting API
curl -X POST http://localhost:7373/admin/reload-model \
  -H "Content-Type: application/json" \
  -d '{"model_path": "/path/to/companion-7b.gguf"}'

---

Command Reference

Indexer Commands

Command	Description	Example
index	Full re-index of vault	cli index
sync	Incremental sync	cli sync
reindex	Force full reindex	cli reindex
status	Show index statistics	cli status

Common Options

All indexer commands support:

• --config PATH : Use alternative config file
• --verbose : Detailed logging

Environment Variables

Variable	Purpose	Example
COMPANION_CONFIG	Config file path	/etc/companion/config.json
COMPANION_DATA_DIR	Data storage root	/var/lib/companion
VAULT_PATH	Override vault location	/home/user/vault

---

Troubleshooting

"No module named 'companion'"

# Install in editable mode
pip install -e "."

# Or set PYTHONPATH
export PYTHONPATH=/path/to/companion:$PYTHONPATH

"Failed to generate embedding"

• Check Ollama is running: curl http://localhost:11434/api/tags
• Verify embedding model is pulled: ollama pull mxbai-embed-large
• Check config.json has correct rag.embedding.base_url

"No results from search"

1. Check index status: cli status
2. Verify vault path is correct in config
3. Run full index: cli index
4. Check file patterns match your notes (default: *.md)

"Port 7373 already in use"

# Find and kill process
lsof -i :7373
kill <PID>

# Or use different port
python -m uvicorn companion.api:app --port 7374

Windows: Scripts won't run

# Set execution policy
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# Or run with explicit bypass
powershell -ExecutionPolicy Bypass -File scripts/install.ps1

---

Systemd Commands (Linux)

If installed as a service:

# Start/stop/restart
sudo systemctl start companion-api
sudo systemctl stop companion-api
sudo systemctl restart companion-api

# Check status
sudo systemctl status companion-api

# View logs
sudo journalctl -u companion-api -f

# Enable auto-start
sudo systemctl enable companion-api

---

Docker Commands

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f companion-api

# Run indexer command
docker-compose exec companion-api python -m companion.indexer_daemon.cli index

# Rebuild after code changes
docker-compose up -d --build

# Stop everything
docker-compose down

---

Performance Tips

Indexing Large Vaults

• First index takes time (1-5 hours for 1000+ notes)
• Subsequent syncs are fast (seconds to minutes)
• Use sync instead of reindex for updates

Memory Usage

• API server: ~500MB-1GB RAM
• Indexer: ~200MB while watching
• LanceDB is disk-based, scales to 100K+ chunks

GPU Acceleration

For fine-tuning (not required for RAG):

• Requires CUDA-capable GPU
• Install unsloth and torch with CUDA support
• Training uses ~10GB VRAM for 7B models

---

Best Practices

1. Index regularly: Run sync daily or use the file watcher
2. Back up vectors: Copy ~/.companion/vectors.lance periodically
3. Use session IDs: Pass session_id to maintain conversation context
4. Monitor citations: Check the sources panel to verify RAG is working
5. Keep Ollama running: The embedding service must be available

---

Getting Help

• Check logs: journalctl -u companion-api or docker-compose logs
• Verify config: python -c "from companion.config import load_config; print(load_config())"
• Test search directly: python -m companion.indexer_daemon.cli search "test query"

---

Next Steps

1. Index your vault
2. Start the API server
3. Open the web UI
4. Ask your first question
5. Explore the citations

Enjoy your personal AI companion!