Oracle is a sophisticated memory and learning system that tracks interactions, learns from corrections, maintains knowledge across sessions, and generates token-efficient context to prevent wasted effort and repeated mistakes.

The Problem

When working with LLMs across multiple sessions:

Context is lost between sessions
Mistakes repeat because corrections aren't remembered
Tokens are wasted explaining the same things
Knowledge doesn't compound - each session starts from zero
Patterns aren't detected - automation opportunities missed

The Solution

Oracle provides:

📝 Session Recording - Track what happens, what works, what doesn't
🧠 Learning from Corrections - When you correct Claude, it's remembered
🔍 Smart Context Injection - Load only relevant knowledge when needed
📊 Pattern Detection - Identify automation opportunities
📈 Knowledge Compounding - Learning accumulates over time
🤖 Auto-Script Generation - Automate repeated patterns

Quick Start

1. Initialize Oracle

python .claude/skills/oracle/scripts/init_oracle.py

This creates .oracle/ directory with knowledge management structure.

2. Record Your First Session

After working with Claude:

python .claude/skills/oracle/scripts/record_session.py --interactive

Answer prompts to record what you learned, what was corrected, decisions made.

3. Load Context Next Session

python .claude/skills/oracle/scripts/load_context.py

Oracle loads relevant knowledge so Claude starts context-aware.

4. Query Knowledge Anytime

python .claude/skills/oracle/scripts/query_knowledge.py "authentication"

Search the knowledge base for relevant information.

Core Features

🎯 Session Recording

Track every session's:

Activities and accomplishments
Files changed and why
Decisions made and rationale
Learnings and discoveries
Corrections and mistakes
Questions asked and answered

Usage:

# Interactive mode (recommended)
python .claude/skills/oracle/scripts/record_session.py --interactive

# Quick mode
python .claude/skills/oracle/scripts/record_session.py \
  --summary "Implemented auth" \
  --learnings "Use bcrypt not md5" \
  --corrections "innerHTML->textContent for user input"

🧠 Knowledge Management

Oracle maintains categorized knowledge:

Category	Purpose	Example
Patterns	Code patterns, architecture decisions	"Use factory pattern for DB connections"
Preferences	Team/user style preferences	"Prefer functional over OOP"
Gotchas	Known issues, pitfalls	"Connection pool must be closed"
Solutions	Proven solutions	"Use cursor-based pagination"
Corrections	Mistakes to avoid	"Don't use innerHTML with user input"

Usage:

# Search all knowledge
python .claude/skills/oracle/scripts/query_knowledge.py "database"

# Filter by category
python .claude/skills/oracle/scripts/query_knowledge.py --category gotchas

# Filter by priority
python .claude/skills/oracle/scripts/query_knowledge.py --priority critical

# Recent learnings
python .claude/skills/oracle/scripts/query_knowledge.py --recent 10

💡 Smart Context Injection

Oracle uses tiered context loading:

Tier 1 (Critical): Always load

Critical gotchas
Recent corrections
High-priority patterns

Tier 2 (Relevant): Load when relevant

Related patterns
Similar solutions
Contextual preferences

Tier 3 (Archive): Load on request

Full history
All solutions
Complete timeline

Usage:

# Session start context
python .claude/skills/oracle/scripts/generate_context.py --session-start

# Task-specific context
python .claude/skills/oracle/scripts/generate_context.py --task "implement API"

# Update claude.md
python .claude/skills/oracle/scripts/generate_context.py --output claude.md --update

🔍 Pattern Detection & Automation

Oracle analyzes sessions to find:

Repeated tasks → automation candidates
Common corrections → update defaults
Frequent queries → add to auto-inject
Token-heavy operations → create scripts

Usage:

# Analyze patterns
python .claude/skills/oracle/scripts/analyze_patterns.py

# Generate automation scripts
python .claude/skills/oracle/scripts/analyze_patterns.py --generate-scripts --threshold 3

Integration

claude.md Integration

Add Oracle context to claude.md:

## Project Knowledge (Oracle)

<!-- ORACLE_CONTEXT_START -->
<!-- Auto-generated - Run: python .claude/skills/oracle/scripts/generate_context.py --output claude.md --update -->
<!-- ORACLE_CONTEXT_END -->

Update it:

python .claude/skills/oracle/scripts/generate_context.py --output claude.md --update

Session Start Hook

Auto-load context at session start:

# Create hook
cat > .claude/hooks/session-start.sh << 'EOF'
#!/bin/bash
python .claude/skills/oracle/scripts/load_context.py
EOF

chmod +x .claude/hooks/session-start.sh

Git Hook Integration

Auto-track commits:

# Create post-commit hook
cat > .git/hooks/post-commit << 'EOF'
#!/bin/bash
python .claude/skills/oracle/scripts/record_commit.py
EOF

chmod +x .git/hooks/post-commit

See References/integration-guide.md for complete integration options.

Directory Structure

.oracle/
├── knowledge/
│   ├── patterns.json          # Code patterns
│   ├── preferences.json       # Team preferences
│   ├── gotchas.json          # Known issues
│   ├── solutions.json        # Proven solutions
│   └── corrections.json      # Historical corrections
├── sessions/
│   └── YYYY-MM-DD_HHMMSS_*.md  # Session logs
├── timeline/
│   └── project_timeline.md   # Chronological history
├── scripts/
│   └── auto_*.sh             # Generated automation
├── hooks/
│   └── *.sh                  # Integration hooks
├── index.json                # Fast lookup index
└── README.md                 # Oracle documentation

Scripts Reference

Script	Purpose
`init_oracle.py`	Initialize Oracle for a project
`record_session.py`	Record session activities and learnings
`query_knowledge.py`	Search knowledge base
`generate_context.py`	Generate context summaries
`analyze_patterns.py`	Detect patterns and automation opportunities
`load_context.py`	Load context (for hooks)
`record_commit.py`	Record git commits (for hooks)

Run any script with --help for detailed options.

Workflow Examples

Example 1: Daily Development

# Morning - load context
python .claude/skills/oracle/scripts/load_context.py

# Work with Claude...

# Evening - record session
python .claude/skills/oracle/scripts/record_session.py --interactive

Example 2: Bug Fix

# Search for related knowledge
python .claude/skills/oracle/scripts/query_knowledge.py "bug keywords"

# Fix bug with Claude...

# Record the fix
python .claude/skills/oracle/scripts/record_session.py \
  --summary "Fixed bug in authentication" \
  --learnings "Root cause was connection timeout - added retry logic"

Example 3: New Feature

# Get context for the feature
python .claude/skills/oracle/scripts/generate_context.py --task "user profile feature"

# Implement feature...

# Record decisions and patterns
python .claude/skills/oracle/scripts/record_session.py --interactive
# Document: decisions made, patterns used, learnings

Example 4: Weekly Maintenance

# Analyze for patterns
python .claude/skills/oracle/scripts/analyze_patterns.py --generate-scripts

# Review knowledge base
python .claude/skills/oracle/scripts/query_knowledge.py --summary

# Update claude.md
python .claude/skills/oracle/scripts/generate_context.py --output claude.md --update

Best Practices

1. Record Sessions Immediately

Don't wait - record while details are fresh.

2. Be Specific in Corrections

❌ "That's wrong" ✅ "Don't use innerHTML -> use textContent to prevent XSS"

3. Use Consistent Tags

Review existing tags before creating new ones.

4. Prioritize Ruthlessly

Critical: Security, data loss, breaking issues
High: Important patterns, frequent gotchas
Medium: Helpful solutions, preferences
Low: Nice-to-know, historical context

5. Leverage Automation

When Oracle suggests automation, implement it.

6. Review Monthly

Knowledge bases get stale - review and update regularly.

7. Integration is Key

Set up hooks so Oracle works automatically.

Philosophy

"What is learned once should never be forgotten. What works should be remembered. What fails should be avoided."

Oracle operates on:

KISS: Simple, readable formats
Token Efficiency: Dense storage, strategic recall
Learning from Feedback: Adapt when corrected
Progressive Recall: Load what's needed, when needed
Human-Readable: No special tools required

Success Indicators

✅ Oracle is working when:

Similar questions get "I remember we..."
Corrections don't repeat
Context is relevant without asking
Knowledge base grows steadily
Scripts reduce repetitive tasks
Timeline shows clear project evolution

❌ Warning signs:

Same corrections repeating
Duplicate knowledge entries
Irrelevant context injections
No automation scripts generated
Timeline has gaps

Documentation

SKILL.md: Full skill definition and workflows
References/knowledge-schema.md: Knowledge entry structure
References/session-log-template.md: Session recording template
References/integration-guide.md: Integration options and patterns
References/pattern-library.md: Common patterns and anti-patterns

Troubleshooting

Context Not Loading

# Check Oracle exists
ls -la .oracle/

# Test manually
python .claude/skills/oracle/scripts/load_context.py --verbose

Knowledge Not Relevant

# Use task-specific context
python .claude/skills/oracle/scripts/generate_context.py --task "specific task"

# Review and update tags
python .claude/skills/oracle/scripts/query_knowledge.py --category patterns

Too Much Context

# Use tier 1 only (critical)
python .claude/skills/oracle/scripts/generate_context.py --tier 1

# Review priorities
python .claude/skills/oracle/scripts/query_knowledge.py --priority critical

Use Cases

Solo Developer

Track personal learnings
Build institutional knowledge
Automate repeated tasks
Prevent repeating mistakes

Team Project

Share knowledge via git
Onboard new members
Maintain consistency
Document tribal knowledge

Open Source

Help contributors understand patterns
Document decisions and rationale
Reduce repetitive questions
Build comprehensive knowledge base

Learning New Technology

Record discoveries
Track corrections
Build reference materials
Compound knowledge over time

Examples

See Assets/ directory for:

Example knowledge entries
Sample session logs
Generated automation scripts

Contributing

Oracle is part of ClaudeShack. Improvements welcome!

Suggest new patterns
Propose script enhancements
Share successful workflows
Report issues

Version

Oracle v1.0

Initial release
Core knowledge management
Session recording
Pattern detection
Context generation
Automation script generation

"Remember everything. Learn from mistakes. Never waste context."