# Knowledge System
The AI Runner knowledge system provides long-term memory capabilities for the LLM, allowing it to remember facts about the user, conversations, and context across sessions.
## Overview
AI Runner uses a **markdown-based knowledge system** with daily files stored in a structured format. Facts are organized by section and indexed for RAG (Retrieval-Augmented Generation) semantic search.
### Key Features
- **Daily Files**: Facts stored in dated markdown files (`YYYY-MM-DD.md`)
- **Section Organization**: Facts organized by category (Identity, Work, Interests, etc.)
- **RAG Integration**: Vector-based retrieval using embeddings for efficient fact recall
- **Human-Readable**: Easy to view, edit, and backup using any text editor
- **Automatic Indexing**: All knowledge files indexed for semantic search
## Architecture
### File Storage
Knowledge is stored as markdown files in:
\`\`\`
~/.local/share/airunner/text/knowledge/
├── 2025-01-15.md
├── 2025-01-16.md
├── 2025-01-17.md
└── ...
\`\`\`
### Daily File Structure
Each daily knowledge file follows this template:
\`\`\`markdown
# Knowledge - 2025-01-15
## Identity
User's name is Joe.
User is a software developer.
## Work & Projects
User works on AI Runner project.
## Interests & Hobbies
User enjoys programming and AI research.
## Preferences
User prefers dark mode interfaces.
## Health & Wellness
## Relationships
## Goals
User wants to create accessible AI tools.
## Notes
\`\`\`
### Sections
Facts are organized into these sections:
| Section | Description |
|---------|-------------|
| **Identity** | Name, age, gender, basic personal info |
| **Work & Projects** | Job, company, current projects |
| **Interests & Hobbies** | Hobbies, topics of interest |
| **Preferences** | Likes, dislikes, habits |
| **Health & Wellness** | Health info (if shared) |
| **Relationships** | Family, friends |
| **Goals** | What user wants to achieve |
| **Notes** | Miscellaneous information |
## How It Works
### Adding Facts
Facts are added through conversation or the LLM tools:
\`\`\`python
# Via tool calling (automatic)
# When user says: "Remember that I prefer Python over JavaScript"
# The LLM calls: record_knowledge(text="User prefers Python over JavaScript",
# section="Preferences")
\`\`\`
### Retrieving Facts
Facts are retrieved via RAG semantic search:
\`\`\`python
from airunner.components.knowledge.knowledge_base import get_knowledge_base
kb = get_knowledge_base()
# Get all context for a query
context = kb.get_context("What programming languages does the user like?")
# Get recent facts
recent = kb.get_recent_facts(days=7)
# Search all facts
matches = kb.search("Python")
\`\`\`
### Memory Tiers
The knowledge system implements a tiered memory approach:
\`\`\`
┌─────────────────────────────────────────────────┐
│ Tier 1: Working Memory (RAM) │
│ - Current conversation context │
│ - Recently accessed facts (cached) │
└─────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────┐
│ Tier 2: Daily Knowledge (Markdown) │
│ - Facts stored in daily .md files │
│ - Organized by section │
│ - Human-readable and editable │
└─────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────┐
│ Tier 3: RAG Semantic Search (Vector Store) │
│ - All knowledge files indexed │
│ - Semantic similarity search │
│ - Retrieved based on query relevance │
└─────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────┐
│ Tier 4: Document Library (RAG) │
│ - Ebooks, PDFs, markdown docs │
│ - Broad document search │
│ - See: RAG Search documentation │
└─────────────────────────────────────────────────┘
\`\`\`
## Usage
### Viewing Your Knowledge
Open any daily knowledge file with a text editor:
\`\`\`bash
# Open today's knowledge file
cat ~/.local/share/airunner/text/knowledge/\$(date +%Y-%m-%d).md
# List all knowledge files
ls ~/.local/share/airunner/text/knowledge/
# Open in your editor
code ~/.local/share/airunner/text/knowledge/
\`\`\`
### Editing Facts
Simply edit the markdown files directly:
1. Open the knowledge directory
2. Find the relevant date file
3. Edit the text under the appropriate section
4. Save the file
Changes are automatically picked up on next RAG index refresh.
### Backup
The knowledge directory can be easily backed up:
\`\`\`bash
# Create a backup
cp -r ~/.local/share/airunner/text/knowledge/ ~/knowledge-backup/
# Restore from backup
cp -r ~/knowledge-backup/* ~/.local/share/airunner/text/knowledge/
\`\`\`
## LLM Tools
The LLM has access to knowledge tools for managing facts:
### record_knowledge
Records a new fact to the knowledge base.
**Parameters:**
- \`text\` (str): The fact to record
- \`section\` (str): Which section to add it to (Identity, Work & Projects, etc.)
### search_knowledge_base
Searches the knowledge base for relevant facts.
**Parameters:**
- \`query\` (str): Search query
### get_user_context
Gets relevant user context for the current conversation.
## Configuration
### Settings
Knowledge system can be configured via settings:
\`\`\`python
# Enable/disable automatic fact extraction
llm_settings.auto_extract_knowledge = True
# Maximum facts to include in context
knowledge_settings.max_context_facts = 20
\`\`\`
## Troubleshooting
### Facts Not Being Remembered
1. Check if knowledge files exist in \`~/.local/share/airunner/text/knowledge/\`
2. Verify the LLM has knowledge tools available
3. Check logs for any errors during tool execution
### Slow Retrieval
1. Ensure RAG indexing is complete
2. Consider reducing the number of historical knowledge files
3. Check that embeddings model is loaded
## See Also
- [RAG Search](Rag-Search.md) - Document-based knowledge retrieval
- [Architecture](Architecture.md) - System design overview
- [Tools](Tools.md) - Available LLM tools