461 lines
12 KiB
Markdown
461 lines
12 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
python .claude/skills/oracle/scripts/load_context.py
|
|
```
|
|
|
|
Oracle loads relevant knowledge so Claude starts context-aware.
|
|
|
|
### 4. Query Knowledge Anytime
|
|
|
|
```bash
|
|
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:**
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
# 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`:
|
|
|
|
```markdown
|
|
## 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:
|
|
```bash
|
|
python .claude/skills/oracle/scripts/generate_context.py --output claude.md --update
|
|
```
|
|
|
|
### Session Start Hook
|
|
|
|
Auto-load context at session start:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# Check Oracle exists
|
|
ls -la .oracle/
|
|
|
|
# Test manually
|
|
python .claude/skills/oracle/scripts/load_context.py --verbose
|
|
```
|
|
|
|
### Knowledge Not Relevant
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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."**
|