Initial commit
This commit is contained in:
Zhongwei Li
460
skills/oracle/README.md
Normal file
460
skills/oracle/README.md
Normal file
@@ -0,0 +1,460 @@
|
||||
# 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."**
|
||||
Reference in New Issue
Block a user