continuous-learning-v2

# Continuous Learning v2 - Instinct-Based Architecture An advanced learning system that turns your Claude Code sessions into reusable knowledge through atomic "instincts" - small learned behaviors with confidence scoring. ## What's New in v2 | Feature | v1 | v2 | |---------|----|----| | Observation | Stop hook (session end) | PreToolUse/PostToolUse (100% reliable) | | Analysis | Main context | Background agent (Haiku) | | Granularity | Full skills | Atomic "instincts" | | Confidence | None | 0.3-0.9 weighted | | Evolution | Direct to skill | Instincts → cluster → skill/command/agent | | Sharing | None | Export/import instincts | ## The Instinct Model An instinct is a small learned behavior: ```yaml --- id: prefer-functional-style trigger: "when writing new functions" confidence: 0.7 domain: "code-style" source: "session-observation" --- # Prefer Functional Style ## Action Use functional patterns over classes when appropriate. ## Evidence - Observed 5 instances of functional pattern preference - User corrected class-based approach to functional on 2025-01-15 ``` **Properties:** - **Atomic** — one trigger, one action - **Confidence-weighted** — 0.3 = tentative, 0.9 = near certain - **Domain-tagged** — code-style, testing, git, debugging, workflow, etc. - **Evidence-backed** — tracks what observations created it ## How It Works ``` Session Activity │ │ Hooks capture prompts + tool use (100% reliable) ▼ ┌─────────────────────────────────────────┐ │ observations.jsonl │ │ (prompts, tool calls, outcomes) │ └─────────────────────────────────────────┘ │ │ Observer agent reads (background, Haiku) ▼ ┌─────────────────────────────────────────┐ │ PATTERN DETECTION │ │ • User corrections → instinct │ │ • Error resolutions → instinct │ │ • Repeated workflows → instinct │ └─────────────────────────────────────────┘ │ │ Creates/updates ▼ ┌─────────────────────────────────────────┐ │ instincts/personal/ │ │ • prefer-functional.md (0.7) │ │ • always-test-first.md (0.9) │ │ • use-zod-validation.md (0.6) │ └─────────────────────────────────────────┘ │ │ /evolve clusters ▼ ┌─────────────────────────────────────────┐ │ evolved/ │ │ • commands/new-feature.md │ │ • skills/testing-workflow.md │ │ • agents/refactor-specialist.md │ └─────────────────────────────────────────┘ ``` ## Quick Start ### 1. Enable Observation Hooks Add to your `~/.claude/settings.json`: ```json { "hooks": { "PreToolUse": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "~/.claude/skills/continuous-learning-v2/hooks/observe.sh pre" }] }], "PostToolUse": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "~/.claude/skills/continuous-learning-v2/hooks/observe.sh post" }] }] } } ``` ### 2. Initialize Directory Structure ```bash mkdir -p ~/.claude/homunculus/{instincts/{personal,inherited},evolved/{agents,skills,commands}} touch ~/.claude/homunculus/observations.jsonl ``` ### 3. Run the Observer Agent (Optional) The observer can run in the background analyzing observations: ```bash # Start background observer ~/.claude/skills/continuous-learning-v2/agents/start-observer.sh ``` ## Commands | Command | Description | |---------|-------------| | `/instinct-status` | Show all learned instincts with confidence | | `/evolve` | Cluster related instincts into skills/commands | | `/instinct-export` | Export instincts for sharing | | `/instinct-import <file>` | Import instincts from others | ## Configuration Edit `config.json`: ```json { "version": "2.0", "observation": { "enabled": true, "store_path": "~/.claude/homunculus/observations.jsonl", "max_file_size_mb": 10, "archive_after_days": 7 }, "instincts": { "personal_path": "~/.claude/homunculus/instincts/personal/", "inherited_path": "~/.claude/homunculus/instincts/inherited/", "min_confidence": 0.3, "auto_approve_threshold": 0.7, "confidence_decay_rate": 0.05 }, "observer": { "enabled": true, "model": "haiku", "run_interval_minutes": 5, "patterns_to_detect": [ "user_corrections", "error_resolutions", "repeated_workflows", "tool_preferences" ] }, "evolution": { "cluster_threshold": 3, "evolved_path": "~/.claude/homunculus/evolved/" } } ``` ## File Structure ``` ~/.claude/homunculus/ ├── identity.json # Your profile, technical level ├── observations.jsonl # Current session observations ├── observations.archive/ # Processed observations ├── instincts/ │ ├── personal/ # Auto-learned instincts │ └── inherited/ # Imported from others └── evolved/ ├── agents/ # Generated specialist agents ├── skills/ # Generated skills └── commands/ # Generated commands ``` ## Integration with Skill Creator When you use the [Skill Creator GitHub App](https://skill-creator.app), it now generates **both**: - Traditional SKILL.md files (for backward compatibility) - Instinct collections (for v2 learning system) Instincts from repo analysis have `source: "repo-analysis"` and include the source repository URL. ## Confidence Scoring Confidence evolves over time: | Score | Meaning | Behavior | |-------|---------|----------| | 0.3 | Tentative | Suggested but not enforced | | 0.5 | Moderate | Applied when relevant | | 0.7 | Strong | Auto-approved for application | | 0.9 | Near-certain | Core behavior | **Confidence increases** when: - Pattern is repeatedly observed - User doesn't correct the suggested behavior - Similar instincts from other sources agree **Confidence decreases** when: - User explicitly corrects the behavior - Pattern isn't observed for extended periods - Contradicting evidence appears ## Why Hooks vs Skills for Observation? > "v1 relied on skills to observe. Skills are probabilistic—they fire ~50-80% of the time based on Claude's judgment." Hooks fire **100% of the time**, deterministically. This means: - Every tool call is observed - No patterns are missed - Learning is comprehensive ## Backward Compatibility v2 is fully compatible with v1: - Existing `~/.claude/skills/learned/` skills still work - Stop hook still runs (but now also feeds into v2) - Gradual migration path: run both in parallel ## Privacy - Observations stay **local** on your machine - Only **instincts** (patterns) can be exported - No actual code or conversation content is shared - You control what gets exported ## Related - [Skill Creator](https://skill-creator.app) - Generate instincts from repo history - [Homunculus](https://github.com/humanplane/homunculus) - Inspiration for v2 architecture - [The Longform Guide](https://x.com/affaanmustafa/status/2014040193557471352) - Continuous learning section --- *Instinct-based learning: teaching Claude your patterns, one observation at a time.*