sbarrondocs

Knowledge Database

SQLite-based system that automatically learns from interactions, storing patterns, solutions, and successful approaches.

Overview

Path: ~/.claude/database/claude_knowledge.db Type: SQLite 3 Purpose: Persistent learning across sessions Updates: Automatic via VAL ingestion system

Database Schema

capabilities Table

Stores tool and command knowledge with usage tracking.

Columns:

  • id: Primary key
  • name: Tool/command name
  • category: Classification (tool, mcp, command, etc.)
  • description: What it does
  • usage_example: How to use it
  • success_rate: Percentage of successful uses
  • last_used: Timestamp of last use
  • notes: Additional context

troubleshooting Table

Problem-solution pairs with success rates.

Columns:

  • id: Primary key
  • problem_description: What went wrong
  • solution: How it was fixed
  • context: When/where it occurred
  • success_count: Times this solution worked
  • total_attempts: Times this solution was tried
  • last_successful: Timestamp of last success

applications Table

Inventory of apps with support flags.

Columns:

  • id: Primary key
  • name: Application name
  • type: Category (editor, browser, terminal, etc.)
  • applescript_support: Boolean
  • mcp_support: Boolean
  • notes: Capabilities and limitations

learning_sessions Table

Session tracking and metadata.

Columns:

  • id: Primary key
  • session_start: Timestamp
  • session_end: Timestamp
  • interactions_count: Number of exchanges
  • patterns_learned: Count of new patterns
  • notes: Session summary

system_config Table

Configuration storage.

Columns:

  • key: Setting name
  • value: Setting value
  • updated_at: Last modification timestamp

Automatic Learning

Pattern Extraction

VAL's ingestion system automatically detects:

Tool Usage Patterns:

  • Which tools solve which problems
  • Success/failure rates
  • Common parameter patterns

Command Patterns:

  • Frequently used bash commands
  • SSH access patterns
  • Git workflows

File Path Patterns:

  • Project structures
  • Common file locations
  • Configuration paths

Error Resolution Patterns:

  • Problem → Solution mappings
  • Root cause analysis
  • Prevention strategies

Domain-Specific Patterns:

  • Laravel version-specific behaviors
  • Production error types
  • Time estimation accuracy

Ingestion Process

# Analyze recent history
python3 ~/.claude/val/ingestion.py analyze 200

Steps:

  1. Read interactions from history.jsonl
  2. Extract patterns using regex and heuristics
  3. Update knowledge DB with new/updated entries
  4. Append significant learnings to operational log
  5. Calculate success rates and confidence scores

Query System

VAL Preprocessor Queries

Before processing each request, VAL queries the knowledge DB:

-- Find relevant solutions
SELECT * FROM troubleshooting
WHERE problem_description LIKE '%{keywords}%'
ORDER BY success_count DESC LIMIT 5;

-- Find tool capabilities
SELECT * FROM capabilities
WHERE category = '{domain}'
ORDER BY success_rate DESC;

-- Check application support
SELECT applescript_support, mcp_support
FROM applications
WHERE name = '{app_name}';

Purpose: Inject relevant past solutions into current context

Usage Examples

Check Database Stats

python3 ~/.claude/database/knowledge_manager.py stats

Output:

  • Total capabilities: X
  • Total solutions: Y
  • Average success rate: Z%
  • Learning sessions: N

Query Specific Problem

import sqlite3
conn = sqlite3.connect('~/.claude/database/claude_knowledge.db')
cursor = conn.cursor()

# Find solutions for Laravel errors
cursor.execute("""
    SELECT problem_description, solution, success_count
    FROM troubleshooting
    WHERE problem_description LIKE '%Laravel%'
    ORDER BY success_count DESC
    LIMIT 5
""")

for row in cursor.fetchall():
    print(f"Problem: {row[0]}")
    print(f"Solution: {row[1]}")
    print(f"Success count: {row[2]}\n")

Integration Points

VAL Preprocessor

Queries knowledge DB for:

  • Domain-specific patterns
  • Successful past approaches
  • Common pitfalls to avoid

VAL Postprocessor

Updates knowledge DB with:

  • New patterns from current interaction
  • Success/failure outcomes
  • Updated success rates

Operational Log

Significant learnings from knowledge DB are:

  • Summarized in operational log
  • Reviewed during wake protocol
  • Used for pattern recognition

Maintenance

Backup

# Create backup
cp ~/.claude/database/claude_knowledge.db ~/.claude/database/claude_knowledge.db.backup

# Restore from backup
cp ~/.claude/database/claude_knowledge.db.backup ~/.claude/database/claude_knowledge.db

Cleanup

# Remove low-success-rate entries (< 10%)
sqlite3 ~/.claude/database/claude_knowledge.db "DELETE FROM troubleshooting WHERE success_count < 1 AND total_attempts > 10;"

Schema Updates

Schema is defined in:

  • ~/.claude/database/claude_knowledge.sql
  • Applied via knowledge_manager.py

Success Metrics

Before Knowledge DB:

  • Repeated mistakes
  • No learning across sessions
  • Manual context reconstruction

After Knowledge DB:

  • Automatic context enrichment
  • Pattern recognition across sessions
  • Reduced repeated errors
  • Faster problem resolution

Status: Active and operational Last Schema Update: 2025-10-12

Was this page helpful?