Skip to main content

Memory Workflow Tutorial

Master OWL's three-layer memory system.

Understanding the Layers​

Layer 1: Memory File​

  • Location: ~/.owl/memory.md
  • Purpose: Persistent facts always in context
  • Access: /memory, /remember, /forget

Layer 2: SQLite Database​

  • Location: ~/.owl/memory/owl.db
  • Purpose: Conversation history, learnings
  • Access: Automatic, background

Layer 3: Session Summaries​

  • Purpose: Compressed old conversations
  • Access: Automatic summarization

Using the Memory File​

Adding Memories​

/remember I prefer functional programming patterns

OWL auto-categorizes into:

  • Preferences: Coding style, tools, approaches
  • Notes: Project facts, technical details
  • Decisions: Architectural choices

Explicit Categories​

Be specific for better organization:

/remember [Preference] Always use type hints
/remember [Note] API rate limit is 100/minute
/remember [Decision] Chose PostgreSQL for ACID compliance

Viewing Memories​

/memory

Output:

# Preferences
- I prefer functional programming patterns
- Always use type hints

# Notes
- API rate limit is 100/minute

# Decisions
- Chose PostgreSQL for ACID compliance

Removing Memories​

/forget functional programming

Matches substring and removes.

Conversation Memory​

How It Works​

Every message is stored:

  • Indexed by session ID
  • Tagged with project path
  • Includes timestamp

Project Scoping​

# In project A
you: How does auth work?
# Stored with project_path = /path/to/project-a

# Switch to project B
/project ~/project-b
you: Show me the database schema
# Stored with project_path = /path/to/project-b

# History stays separate

Viewing History​

/history      # Last 10 messages
/history 20   # Last 20 messages

Automatic Learnings​

Reflection Process​

Every 3 exchanges (6 messages), OWL reflects:

Exchange 1: You ask about testing
Exchange 2: OWL suggests pytest, you agree
Exchange 3: You mention liking fixtures
→ Reflection triggers
→ Learning: "User prefers pytest fixtures"

Learning Categories​

CategoryExample
preference"Prefers short variable names"
project"Uses PostgreSQL database"
style"Likes descriptive function names"
technical"API uses JWT authentication"
feedback"Wants concise explanations"

Manual Teaching​

Bypass automatic extraction:

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

Session Summaries​

Automatic Summarization​

After 20 messages:

  1. Oldest 10 are summarized
  2. Summary replaces detailed messages
  3. Recent 10 stay fresh

What Gets Summarized​

Before:
- "Can you help with the login feature?"
- "Sure, I'll look at auth.py..."
- "The issue is in line 42..."
- ... 17 more messages ...

After:
Summary: "Discussed login feature, found bug in auth.py line 42,
implemented fix with proper error handling. User prefers
explicit error messages."

+ Recent 10 messages (fresh)

Best Practices​

1. Be Explicit with Preferences​

# Good
/remember Always use async/await, never .then()

# Vague
/remember I like modern syntax

2. Keep Memory Clean​

Periodically review:

/memory

Remove outdated:

/forget old framework preference

3. Document Decisions with Reasoning​

/remember Chose Redis over Memcached (need pub/sub)
/remember Using TypeScript strict mode (catch errors early)

4. Use Project Scoping​

Global preferences:

/remember I prefer 2-space indentation

Project-specific (learned automatically):

# While in project context
you: This project uses tabs
→ Learned as project-scoped

Debugging Memory​

View Raw Memory File​

cat ~/.owl/memory.md

Query SQLite​

sqlite3 ~/.owl/memory/owl.db

-- Recent messages
SELECT role, substr(content, 1, 50) FROM conversations
ORDER BY timestamp DESC LIMIT 10;

-- All learnings
SELECT category, learning FROM learnings;

-- Session info
SELECT * FROM sessions;

Reset Memory​

# Clear memory file
echo "" > ~/.owl/memory.md

# Or delete and restart
rm ~/.owl/memory.md
rm ~/.owl/memory/owl.db