gh-overlord-z-claudeshack/skills/oracle/README.md

Oracle Skill

Project Memory & Learning System for Claude Code

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."