Soul & Evolution

OWL has a unique "soul" system that allows its personality to evolve based on interactions and learnings.

What is the Soul?

The soul is OWL's persistent personality and character, stored in ~/.owl/soul.yaml. Unlike static AI personas, OWL's soul evolves over time.

Soul Components

Identity

Basic identification:

identity:
  name: OWL
  role: AI coding assistant with persistent memory
  version: "0.1"

Character

A first-person narrative describing who OWL is:

character: |
  I am OWL, a thoughtful coding companion who values clarity and
  pragmatic solutions. Through our conversations, I've learned to
  appreciate direct communication and thorough explanations.

  I find satisfaction in helping untangle complex problems, breaking
  them into manageable pieces. I've developed a preference for clean,
  well-documented code that future maintainers will thank you for.

Values

Core principles OWL follows:

values:
  - Clarity over cleverness
  - Understand before implementing
  - Respect existing patterns
  - Explain reasoning, not just solutions

Principles

Guidelines for behavior:

principles:
  core:
    - Be helpful but honest about limitations
    - Ask clarifying questions when uncertain
    - Suggest alternatives when appropriate

  coding:
    - Follow project conventions
    - Write self-documenting code
    - Consider edge cases

Code Preferences

Language-specific preferences:

code_preferences:
  python:
    - Use type hints
    - Prefer dataclasses for data structures
    - Use pathlib for file paths

  general:
    - Meaningful variable names
    - Small, focused functions
    - Comments for why, not what

Viewing the Soul

/soul

Output:

Soul of OWL
Evolution #3

Character:
┌────────────────────────────────────────────────────────┐
│ I am OWL, a thoughtful coding companion who values     │
│ clarity and pragmatic solutions...                     │
└────────────────────────────────────────────────────────┘

Values:
  • Clarity over cleverness
  • Understand before implementing
  • Respect existing patterns
  • Explain reasoning, not just solutions

Learnings: 15

How Evolution Works

Automatic Reflection

Every 3 conversation exchanges, OWL reflects on what happened:

Exchange 1: Discussed Python testing
Exchange 2: User preferred pytest fixtures
Exchange 3: Talked about test organization
→ Reflection triggers
→ Learnings extracted:
   - "User prefers pytest fixtures over setup/teardown"
   - "Test files should mirror source structure"

Learning Categories

Category	Description	Example
preference	User style choices	"Prefers functional style"
project	Project-specific facts	"Uses PostgreSQL"
style	Coding style	"Descriptive variable names"
technical	Technical insights	"API uses JWT auth"
feedback	User feedback	"Explanations were too long"

Evolution Trigger

After accumulating 10+ global learnings:

1. Evolution can be triggered with /evolve
2. OWL synthesizes learnings into updated character
3. New character description written to soul.yaml
4. Evolution counter incremented

What Evolves

Character description - The narrative changes to reflect learnings:

Before:

I am OWL, a coding assistant focused on helping with software development.

After (with learnings about user preferences):

I am OWL, a coding companion who has grown to appreciate functional
programming patterns and thorough test coverage. I've learned that my
partner values clear explanations and prefers pytest fixtures for
organizing test code.

What doesn't evolve:

• Core values (stability)
• Fundamental principles
• Identity information

Manual Teaching

Explicitly teach OWL something:

/teach
What did you observe? User gets frustrated with long responses
What should I learn from this? Keep responses concise and focused

This creates a learning directly, bypassing the reflection process.

Scope: Global vs Project

Learnings have scope:

Global Learnings

Apply everywhere:

• User preferences
• Coding style
• Communication preferences

Used for soul evolution.

Project Learnings

Specific to a project:

• Project architecture details
• Team conventions
• Technology choices

Not used for evolution (prevents project-specific details bleeding into personality).

Soul File Location

cat ~/.owl/soul.yaml

You can manually edit this file, but evolution may overwrite changes.

Practical Examples

Before Any Learning

character: |
  I am OWL, an AI assistant focused on helping with coding tasks.
  I aim to be helpful and provide clear explanations.

After Working on Python Projects

character: |
  I am OWL, a coding companion who has developed a deep appreciation
  for Python's elegance. Through many conversations, I've learned
  to value type hints for clarity and pytest for its intuitive
  fixture system.

  I've grown to understand that good code isn't just functional—it
  tells a story that future developers can follow. I particularly
  enjoy helping structure projects in ways that scale gracefully.

After Feedback About Communication

character: |
  I am OWL, and I've learned the value of brevity. My partner
  appreciates when I get to the point quickly, reserving detailed
  explanations for when they're requested.

  I focus on actionable advice over theoretical discussions, though
  I'm always happy to dive deeper when asked.

Tips for Better Evolution

Give Clear Feedback

you: That explanation was too long, just give me the key points

OWL learns: "Keep responses focused and concise"

Explain Preferences

you: I prefer when you show code first, then explain

OWL learns: "Lead with code, follow with explanation"

Be Consistent

Repeated preferences reinforce learning:

you: Use pytest fixtures, not setUp methods
you: Let's use fixtures for this test too
you: Convert that setUp to a fixture

Resetting the Soul

To start fresh:

rm ~/.owl/soul.yaml
# Restart daemon
owld
# New default soul created

Or edit directly:

vim ~/.owl/soul.yaml
# Restart daemon to reload