跳轉至

Knowledge System - Brain, RAG & Patterns

Boring's intelligent memory system that learns and remembers across projects.

🧠 Architecture Overview

┌─────────────────────────────────────────────────────────┐
│                 KNOWLEDGE SYSTEM                        │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  ~/.boring/brain/          (Global - All Projects)     │
│  ├── patterns/             Learned error solutions     │
│  ├── rubrics/              Evaluation criteria         │
│  ├── shadow_config.json    Shadow Mode settings        │
│  └── quality_history.json  Score trends                │
│                                                         │
│  .boring/memory/           (Project-Specific)          │
│  ├── sessions/             Session history             │
│  ├── db.sqlite             Structured memory           │
│  └── rag_index/            Web/Doc embeddings          │
│                                                         │
│  .boring/cache/            (Ephemeral - Temp)          │
│  └── rag_cache/            Code embeddings             │
│                                                         │
└─────────────────────────────────────────────────────────┘

📁 Directory Reference

Directory Scope Purpose Migration
~/.boring/brain/ Global Cross-project knowledge Copy to new machine
.boring/memory/ Project Project-specific context Commit to repo
.boring/cache/ Temp Ephemeral cache Regenerated

🧠 .boring/brain (Global Knowledge)

Location

  • Linux/macOS: ~/.boring/brain/
  • Windows: C:\Users\<username>\.boring\brain\

Contents

patterns/ - Learned Patterns

{
  "error_patterns": [
    {
      "error": "ModuleNotFoundError: No module named 'foo'",
      "solution": "pip install foo",
      "confidence": 0.95,
      "occurrences": 15
    }
  ]
}

AI learns from your error-solution pairs and applies them automatically.

rubrics/ - Evaluation Criteria

# production-ready.md
- [ ] All tests passing (100%)
- [ ] No security vulnerabilities
- [ ] Documentation complete
- [ ] Performance benchmarked

Custom rubrics for boring_evaluate.

shadow_config.json - Security Settings

{
  "level": "STRICT",
  "auto_approve_patterns": ["*.md", "docs/*"],
  "always_block_patterns": ["*.env", "secrets/*"]
}

Persistent across sessions.

Migration

# Backup
cp -r ~/.boring/brain ~/boring_brain_backup

# Restore on new machine
cp -r ~/boring_brain_backup ~/.boring/brain

📂 .boring/memory (Project Knowledge)

Location

  • In your project root: .boring/memory/

Contents

db.sqlite - Structured Data

Contains session logs, tool outputs, and project context.

sessions/ - Conversation History

JSON files storing raw conversation logs for context restoration.

Best Practice

# Commit to repo for team sharing
git add .boring/memory/
git commit -m "docs: project context and decisions"

🔍 RAG System

How It Works

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  Your Code   │ ──▶ │   Indexer    │ ──▶ │ Vector DB    │
│  (src/*.py)  │     │ (embeddings) │     │ (ChromaDB)   │
└──────────────┘     └──────────────┘     └──────────────┘
                                                 │
                                                 ▼
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│   Results    │ ◀── │   Ranker     │ ◀── │ Hybrid Search│
│ (top_k=10)   │     │ (reranking)  │     │ Vector+BM25  │
└──────────────┘     └──────────────┘     └──────────────┘

Features

Feature Description
Hybrid Search Vector (semantic) + BM25 (keyword)
Dependency Expansion Includes related files via import graph
Incremental Index Only re-indexes changed files
Auto-Update RAGWatcher detects file changes (V10.18.3+)

Commands

# Build index
boring_rag_index(project_path=".", force=False)

# Search
boring_rag_search(
    query="authentication middleware",
    top_k=10,
    expand_graph=True
)

# Reload
boring_rag_reload(project_path=".")

Storage

  • Index location: .boring/memory/rag_index/
  • Size: ~1MB per 1000 files
  • Regeneration: Automatic if missing

📚 Patterns, FeedbackLearner & Active Recall

Cognitive Reflexes (Active Recall)

Starting in V10.31, the Agent possesses Active Recall. When it encounters an error (e.g., pytest failure), it doesn't just "try again." It queries the global Brain for similar past errors and retrieves proven solutions.

Flow: 1. Error Occurs: Agent captures ModuleNotFoundError. 2. Reflex Query: Agent calls boring_suggest_next(error_message="..."). 3. Brain Retrieval: Brain scans patterns.json for semantic matches. 4. Solution Injection: If a high-confidence match (e.g., 95%) is found, the solution is injected directly into the Agent's context.

How Patterns Are Learned

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│ AI Response  │ ──▶ │FeedbackLearner│ ──▶ │ Pattern DB   │
│ "Fixed by X" │     │ (extraction) │     │ (.boring/brain)│
└──────────────┘     └──────────────┘     └──────────────┘
                             │
                             ▼
                    Next time: Auto-apply!

Pattern Types

Type Example
Error Solutions ImportError → pip install X
Code Patterns Auth middleware structure
Refactoring Extract function pattern

Manual Learning

# Trigger learning from session
boring_learn(
    project_path=".",
    topics=["error-handling", "testing", "patterns"]
)

🚚 Migration Guide

To New Machine

# 1. Copy global knowledge
scp -r ~/.boring/brain user@newmachine:~/

# 2. Clone project (includes .boring/memory)
git clone your-repo

# 3. Rebuild cache (automatic on first use)
boring rag index

To Team Members

# In .gitignore
.boring/cache/          # Don't commit cache

# Commit project knowledge
git add .boring/memory/
git add .boring.toml    # Project config

Environment Variables

# Custom brain location
export BORING_BRAIN_PATH="/path/to/shared/brain"

# Custom cache location
export BORING_CACHE_PATH="/tmp/boring_cache"

See Also