Skip to main content

FAQ

Frequently asked questions about OWL.

General​

What is OWL?​

OWL is a local AI daemon with persistent memory, project awareness, and an evolving personality. It runs entirely on your machine using Ollama.

Is my data sent anywhere?​

No. Everything runs locally:

  • Ollama for LLM inference
  • SQLite for storage
  • ChromaDB for vectors

No external API calls are made.

What models work with OWL?​

Any Ollama-compatible model:

  • llama3.2 (default)
  • mistral, mixtral
  • codellama
  • llama2, llama3
  • And many more

Can I use OpenAI/Anthropic APIs?​

Currently only Ollama is supported. API providers may be added in the future.

Installation​

How do I install OWL?​

One command:

curl -sSL https://kavin-ps.io/owl/install.sh | bash

This installs Ollama, pulls models, and sets up OWL globally.

How do I upgrade OWL?​

uv tool upgrade owl

How do I uninstall OWL?​

uv tool uninstall owl
rm -rf ~/.owl  # Optional: remove data

Usage​

How do I switch models?​

Edit ~/.owl/config.yaml:

llm:
  model: mistral:latest

Then restart OWL:

owl stop
owl

How do I clear conversation history?​

/new  # Start fresh session

Can I use OWL with multiple projects?​

Yes. Switch with /project <path>. History is scoped per project.

How do I backup my data?​

Copy the ~/.owl directory:

cp -r ~/.owl ~/owl-backup

Memory & Learning​

What does OWL remember?​

  1. Memory file: Facts you explicitly tell it (/remember)
  2. Conversation history: Recent messages
  3. Learnings: Auto-extracted insights
  4. Knowledge base: Documents you've added

How does evolution work?​

After 10+ learnings accumulate, use /evolve to trigger character evolution. OWL synthesizes learnings into an updated personality description.

Can I edit the soul directly?​

Yes:

vim ~/.owl/soul.yaml
owl stop && owl  # Restart to reload

Tools​

Why can't OWL write files?​

Check your profile:

/tools

Switch to coding or full:

/tools coding

Are shell commands safe?​

Shell commands (run_command) are only available in full profile. Use with caution - OWL can run any command you could.

Can I add custom tools?​

Not yet through configuration, but you can modify owl/tools/file_ops.py and register new tools in owl/tools/registry.py.

Technical​

Where is data stored?​

~/.owl/
├── config.yaml      # Configuration
├── soul.yaml        # Personality
├── memory.md        # Memory file
├── memory/owl.db    # SQLite database
└── knowledge/       # ChromaDB vectors

How much disk space does OWL use?​

Minimal. Typical usage:

  • Base: ~1MB
  • Per conversation: ~10KB
  • Knowledge base: ~1KB per chunk

Can I run multiple OWL instances?​

Not recommended. The daemon uses a single socket. Multiple CLI instances can connect to one daemon.

How do I debug issues?​

  1. Check daemon output for errors
  2. Enable debug logging in ~/.owl/config.yaml:
daemon:
  log_level: DEBUG
  1. Restart OWL

Contributing​

How can I contribute?​

OWL is open source. Contributions welcome:

  • Bug reports
  • Feature requests
  • Pull requests
  • Documentation improvements

Where do I report bugs?​

GitHub Issues: github.com/kavinps/owl/issues