continuous-learning-v2

# Continuous Learning v2.1 - 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. **v2.1** adds **project-scoped instincts** — React patterns stay in your React project, Python conventions stay in your Python project, and universal patterns (like "always validate input") are shared globally. ## When to Activate - Setting up automatic learning from Claude Code sessions - Configuring instinct-based behavior extraction via hooks - Tuning confidence thresholds for learned behaviors - Reviewing, exporting, or importing instinct libraries - Evolving instincts into full skills, commands, or agents - Managing project-scoped vs global instincts - Promoting instincts from project to global scope ## What's New in v2.1 | Feature | v2.0 | v2.1 | |---------|------|------| | Storage | Global (~/.claude/homunculus/) | Project-scoped (projects/<hash>/) | | Scope | All instincts apply everywhere | Project-scoped + global | | Detection | None | git remote URL / repo path | | Promotion | N/A | Project → global when seen in 2+ projects | | Commands | 4 (status/evolve/export/import) | 6 (+promote/projects) | | Cross-project | Contamination risk | Isolated by default | ## What's New in v2 (vs v1) | 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" scope: project project_id: "a1b2c3d4e5f6" project_name: "my-react-app" --- # 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 - **Scope-aware** -- `project` (default) or `global` ## How It Works ``` Session Activity (in a git repo) | | Hooks capture prompts + tool use (100% reliable) | + detect project context (git remote / repo path) v +---------------------------------------------+ | projects/<project-hash>/observations.jsonl | | (prompts, tool calls, outcomes, project) | +---------------------------------------------+ | | Observer agent reads (background, Haiku) v +---------------------------------------------+ | PATTERN DETECTION | | * User corrections -> instinct | | * Error resolutions -> instinct | | * Repeated workflows -> instinct | | * Scope decision: project or global? | +---------------------------------------------+ | | Creates/updates v +---------------------------------------------+ | projects/<project-hash>/instincts/personal/ | | * prefer-functional.yaml (0.7) [project] | | * use-react-hooks.yaml (0.9) [project] | +---------------------------------------------+ | instincts/personal/ (GLOBAL) | | * always-validate-input.yaml (0.85) [global]| | * grep-before-edit.yaml (0.6) [global] | +---------------------------------------------+ | | /evolve clusters + /promote v +---------------------------------------------+ | projects/<hash>/evolved/ (project-scoped) | | evolved/ (global) | | * commands/new-feature.md | | * skills/testing-workflow.md | | * agents/refactor-specialist.md | +---------------------------------------------+ ``` ## Project Detection The system automatically detects your current project: 1. **`CLAUDE_PROJECT_DIR` env var** (highest priority) 2. **`git remote get-url origin`** -- hashed to create a portable project ID (same repo on different machines gets the same ID) 3. **`git rev-parse --show-toplevel`** -- fallback using repo path (machine-specific) 4. **Global fallback** -- if no project is detected, instincts go to global scope Each project gets a 12-character hash ID (e.g., `a1b2c3d4e5f6`). A registry file at `~/.claude/homunculus/projects.json` maps IDs to human-readable names. ## Quick Start ### 1. Enable Observation Hooks Add to your `~/.claude/settings.json`. **If installed as a plugin** (recommended): ```json { "hooks": { "PreToolUse": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/skills/continuous-learning-v2/hooks/observe.sh" }] }], "PostToolUse": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/skills/continuous-learning-v2/hooks/observe.sh" }] }] } } ``` **If installed manually** to `~/.claude/skills`: ```json { "hooks": { "PreToolUse": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "~/.claude/skills/continuous-learning-v2/hooks/observe.sh" }] }], "PostToolUse": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "~/.claude/skills/continuous-learning-v2/hooks/observe.sh" }] }] } } ``` ### 2. Initialize Directory Structure The system creates directories automatically on first use, but you can also create them manually: ```bash # Global directories mkdir -p ~/.claude/homunculus/{instincts/{personal,inherited},evolved/{agents,skills,commands},projects} # Project directories are auto-created when the hook first runs in a git repo ``` ### 3. Use the Instinct Commands ```bash /instinct-status # Show learned instincts (project + global) /evolve # Cluster related instincts into skills/commands /instinct-export # Export instincts to file /instinct-import # Import instincts from others /promote # Promote project instincts to global scope /projects # List all known projects and their instinct counts ``` ## Commands | Command | Description | |---------|-------------| | `/instinct-status` | Show all instincts (project-scoped + global) with confidence | | `/evolve` | Cluster related instincts into skills/commands, suggest promotions | | `/instinct-export` | Export instincts (filterable by scope/domain) | | `/instinct-import <file>` | Import instincts with scope control | | `/promote [id]` | Promote project instincts to global scope | | `/projects` | List all known projects and their instinct counts | ## Configuration Edit `config.json` to control the background observer: ```json { "version": "2.1", "observer": { "enabled": false, "run_interval_minutes": 5, "min_observations_to_analyze": 20 } } ``` | Key | Default | Description | |-----|---------|-------------| | `observer.enabled` | `false` | Enable the background observer agent | | `observer.run_interval_minutes` | `5` | How often the observer analyzes observations | | `observer.min_observations_to_analyze` | `20` | Minimum observations before analysis runs | Other behavior (observation capture, instinct thresholds, project scoping, promotion criteria) is configured via code defaults in `instinct-cli.py` and `observe.sh`. ## File Structure ``` ~/.claude/homunculus/ +-- identity.json # Your profile, technical level +-- projects.json # Registry: project hash -> name/path/remote +-- observations.jsonl # Global observations (fallback) +-- instincts/ | +-- personal/ # Global auto-learned instincts | +-- inherited/ # Global imported instincts +-- evolved/ | +-- agents/ # Global generated agents | +-- skills/ # Global generated skills | +-- commands/ # Global generated commands +-- projects/ +-- a1b2c3d4e5f6/ # Project hash (from git remote URL) | +-- project.json # Per-project metadata mirror (id/name/root/remote) | +-- observations.jsonl | +-- observations.archive/ | +-- instincts/ | | +-- personal/ # Project-specific auto-learned | | +-- inherited/ # Project-specific imported | +-- evolved/ | +-- skills/ | +-- commands/ | +-- agents/ +-- f6e5d4c3b2a1/ # Another project +-- ... ``` ## Scope Decision Guide | Pattern Type | Scope | Examples | |-------------|-------|---------| | Language/framework conventions | **project** | "Use React hooks", "Follow Django REST patterns" | | File structure preferences | **project** | "Tests in `__tests__`/", "Components in src/components/" | | Code style | **project** | "Use functional style", "Prefer dataclasses" |