|
| 1 | +--- |
| 2 | +name: continuous-learning-v2 |
| 3 | +description: Instinct-based learning system that observes sessions via hooks, creates atomic instincts with confidence scoring, and evolves them into skills/commands/agents. |
| 4 | +version: 2.0.0 |
| 5 | +--- |
| 6 | + |
| 7 | +# Continuous Learning v2 - Instinct-Based Architecture |
| 8 | + |
| 9 | +An advanced learning system that turns your Claude Code sessions into reusable knowledge through atomic "instincts" - small learned behaviors with confidence scoring. |
| 10 | + |
| 11 | +## What's New in v2 |
| 12 | + |
| 13 | +| Feature | v1 | v2 | |
| 14 | +|---------|----|----| |
| 15 | +| Observation | Stop hook (session end) | PreToolUse/PostToolUse (100% reliable) | |
| 16 | +| Analysis | Main context | Background agent (Haiku) | |
| 17 | +| Granularity | Full skills | Atomic "instincts" | |
| 18 | +| Confidence | None | 0.3-0.9 weighted | |
| 19 | +| Evolution | Direct to skill | Instincts → cluster → skill/command/agent | |
| 20 | +| Sharing | None | Export/import instincts | |
| 21 | + |
| 22 | +## The Instinct Model |
| 23 | + |
| 24 | +An instinct is a small learned behavior: |
| 25 | + |
| 26 | +```yaml |
| 27 | +--- |
| 28 | +id: prefer-functional-style |
| 29 | +trigger: "when writing new functions" |
| 30 | +confidence: 0.7 |
| 31 | +domain: "code-style" |
| 32 | +source: "session-observation" |
| 33 | +--- |
| 34 | + |
| 35 | +# Prefer Functional Style |
| 36 | + |
| 37 | +## Action |
| 38 | +Use functional patterns over classes when appropriate. |
| 39 | + |
| 40 | +## Evidence |
| 41 | +- Observed 5 instances of functional pattern preference |
| 42 | +- User corrected class-based approach to functional on 2025-01-15 |
| 43 | +``` |
| 44 | +
|
| 45 | +**Properties:** |
| 46 | +- **Atomic** — one trigger, one action |
| 47 | +- **Confidence-weighted** — 0.3 = tentative, 0.9 = near certain |
| 48 | +- **Domain-tagged** — code-style, testing, git, debugging, workflow, etc. |
| 49 | +- **Evidence-backed** — tracks what observations created it |
| 50 | +
|
| 51 | +## How It Works |
| 52 | +
|
| 53 | +``` |
| 54 | +Session Activity |
| 55 | + │ |
| 56 | + │ Hooks capture prompts + tool use (100% reliable) |
| 57 | + ▼ |
| 58 | +┌─────────────────────────────────────────┐ |
| 59 | +│ observations.jsonl │ |
| 60 | +│ (prompts, tool calls, outcomes) │ |
| 61 | +└─────────────────────────────────────────┘ |
| 62 | + │ |
| 63 | + │ Observer agent reads (background, Haiku) |
| 64 | + ▼ |
| 65 | +┌─────────────────────────────────────────┐ |
| 66 | +│ PATTERN DETECTION │ |
| 67 | +│ • User corrections → instinct │ |
| 68 | +│ • Error resolutions → instinct │ |
| 69 | +│ • Repeated workflows → instinct │ |
| 70 | +└─────────────────────────────────────────┘ |
| 71 | + │ |
| 72 | + │ Creates/updates |
| 73 | + ▼ |
| 74 | +┌─────────────────────────────────────────┐ |
| 75 | +│ instincts/personal/ │ |
| 76 | +│ • prefer-functional.md (0.7) │ |
| 77 | +│ • always-test-first.md (0.9) │ |
| 78 | +│ • use-zod-validation.md (0.6) │ |
| 79 | +└─────────────────────────────────────────┘ |
| 80 | + │ |
| 81 | + │ /evolve clusters |
| 82 | + ▼ |
| 83 | +┌─────────────────────────────────────────┐ |
| 84 | +│ evolved/ │ |
| 85 | +│ • commands/new-feature.md │ |
| 86 | +│ • skills/testing-workflow.md │ |
| 87 | +│ • agents/refactor-specialist.md │ |
| 88 | +└─────────────────────────────────────────┘ |
| 89 | +``` |
| 90 | + |
| 91 | +## Quick Start |
| 92 | + |
| 93 | +### 1. Enable Observation Hooks |
| 94 | + |
| 95 | +Add to your `~/.claude/settings.json`: |
| 96 | + |
| 97 | +```json |
| 98 | +{ |
| 99 | + "hooks": { |
| 100 | + "PreToolUse": [{ |
| 101 | + "matcher": "*", |
| 102 | + "hooks": [{ |
| 103 | + "type": "command", |
| 104 | + "command": "~/.claude/skills/continuous-learning-v2/hooks/observe.sh pre" |
| 105 | + }] |
| 106 | + }], |
| 107 | + "PostToolUse": [{ |
| 108 | + "matcher": "*", |
| 109 | + "hooks": [{ |
| 110 | + "type": "command", |
| 111 | + "command": "~/.claude/skills/continuous-learning-v2/hooks/observe.sh post" |
| 112 | + }] |
| 113 | + }] |
| 114 | + } |
| 115 | +} |
| 116 | +``` |
| 117 | + |
| 118 | +### 2. Initialize Directory Structure |
| 119 | + |
| 120 | +```bash |
| 121 | +mkdir -p ~/.claude/homunculus/{instincts/{personal,inherited},evolved/{agents,skills,commands}} |
| 122 | +touch ~/.claude/homunculus/observations.jsonl |
| 123 | +``` |
| 124 | + |
| 125 | +### 3. Run the Observer Agent (Optional) |
| 126 | + |
| 127 | +The observer can run in the background analyzing observations: |
| 128 | + |
| 129 | +```bash |
| 130 | +# Start background observer |
| 131 | +~/.claude/skills/continuous-learning-v2/agents/start-observer.sh |
| 132 | +``` |
| 133 | + |
| 134 | +## Commands |
| 135 | + |
| 136 | +| Command | Description | |
| 137 | +|---------|-------------| |
| 138 | +| `/instinct-status` | Show all learned instincts with confidence | |
| 139 | +| `/evolve` | Cluster related instincts into skills/commands | |
| 140 | +| `/instinct-export` | Export instincts for sharing | |
| 141 | +| `/instinct-import <file>` | Import instincts from others | |
| 142 | + |
| 143 | +## Configuration |
| 144 | + |
| 145 | +Edit `config.json`: |
| 146 | + |
| 147 | +```json |
| 148 | +{ |
| 149 | + "version": "2.0", |
| 150 | + "observation": { |
| 151 | + "enabled": true, |
| 152 | + "store_path": "~/.claude/homunculus/observations.jsonl", |
| 153 | + "max_file_size_mb": 10, |
| 154 | + "archive_after_days": 7 |
| 155 | + }, |
| 156 | + "instincts": { |
| 157 | + "personal_path": "~/.claude/homunculus/instincts/personal/", |
| 158 | + "inherited_path": "~/.claude/homunculus/instincts/inherited/", |
| 159 | + "min_confidence": 0.3, |
| 160 | + "auto_approve_threshold": 0.7, |
| 161 | + "confidence_decay_rate": 0.05 |
| 162 | + }, |
| 163 | + "observer": { |
| 164 | + "enabled": true, |
| 165 | + "model": "haiku", |
| 166 | + "run_interval_minutes": 5, |
| 167 | + "patterns_to_detect": [ |
| 168 | + "user_corrections", |
| 169 | + "error_resolutions", |
| 170 | + "repeated_workflows", |
| 171 | + "tool_preferences" |
| 172 | + ] |
| 173 | + }, |
| 174 | + "evolution": { |
| 175 | + "cluster_threshold": 3, |
| 176 | + "evolved_path": "~/.claude/homunculus/evolved/" |
| 177 | + } |
| 178 | +} |
| 179 | +``` |
| 180 | + |
| 181 | +## File Structure |
| 182 | + |
| 183 | +``` |
| 184 | +~/.claude/homunculus/ |
| 185 | +├── identity.json # Your profile, technical level |
| 186 | +├── observations.jsonl # Current session observations |
| 187 | +├── observations.archive/ # Processed observations |
| 188 | +├── instincts/ |
| 189 | +│ ├── personal/ # Auto-learned instincts |
| 190 | +│ └── inherited/ # Imported from others |
| 191 | +└── evolved/ |
| 192 | + ├── agents/ # Generated specialist agents |
| 193 | + ├── skills/ # Generated skills |
| 194 | + └── commands/ # Generated commands |
| 195 | +``` |
| 196 | + |
| 197 | +## Integration with Skill Creator |
| 198 | + |
| 199 | +When you use the [Skill Creator GitHub App](https://skill-creator.app), it now generates **both**: |
| 200 | +- Traditional SKILL.md files (for backward compatibility) |
| 201 | +- Instinct collections (for v2 learning system) |
| 202 | + |
| 203 | +Instincts from repo analysis have `source: "repo-analysis"` and include the source repository URL. |
| 204 | + |
| 205 | +## Confidence Scoring |
| 206 | + |
| 207 | +Confidence evolves over time: |
| 208 | + |
| 209 | +| Score | Meaning | Behavior | |
| 210 | +|-------|---------|----------| |
| 211 | +| 0.3 | Tentative | Suggested but not enforced | |
| 212 | +| 0.5 | Moderate | Applied when relevant | |
| 213 | +| 0.7 | Strong | Auto-approved for application | |
| 214 | +| 0.9 | Near-certain | Core behavior | |
| 215 | + |
| 216 | +**Confidence increases** when: |
| 217 | +- Pattern is repeatedly observed |
| 218 | +- User doesn't correct the suggested behavior |
| 219 | +- Similar instincts from other sources agree |
| 220 | + |
| 221 | +**Confidence decreases** when: |
| 222 | +- User explicitly corrects the behavior |
| 223 | +- Pattern isn't observed for extended periods |
| 224 | +- Contradicting evidence appears |
| 225 | + |
| 226 | +## Why Hooks vs Skills for Observation? |
| 227 | + |
| 228 | +> "v1 relied on skills to observe. Skills are probabilistic—they fire ~50-80% of the time based on Claude's judgment." |
| 229 | +
|
| 230 | +Hooks fire **100% of the time**, deterministically. This means: |
| 231 | +- Every tool call is observed |
| 232 | +- No patterns are missed |
| 233 | +- Learning is comprehensive |
| 234 | + |
| 235 | +## Backward Compatibility |
| 236 | + |
| 237 | +v2 is fully compatible with v1: |
| 238 | +- Existing `~/.claude/skills/learned/` skills still work |
| 239 | +- Stop hook still runs (but now also feeds into v2) |
| 240 | +- Gradual migration path: run both in parallel |
| 241 | + |
| 242 | +## Privacy |
| 243 | + |
| 244 | +- Observations stay **local** on your machine |
| 245 | +- Only **instincts** (patterns) can be exported |
| 246 | +- No actual code or conversation content is shared |
| 247 | +- You control what gets exported |
| 248 | + |
| 249 | +## Related |
| 250 | + |
| 251 | +- [Skill Creator](https://skill-creator.app) - Generate instincts from repo history |
| 252 | +- [Homunculus](https://github.com/humanplane/homunculus) - Inspiration for v2 architecture |
| 253 | +- [The Longform Guide](https://x.com/affaanmustafa/status/2014040193557471352) - Continuous learning section |
| 254 | + |
| 255 | +--- |
| 256 | + |
| 257 | +*Instinct-based learning: teaching Claude your patterns, one observation at a time.* |
0 commit comments