continuous-learning-v2

name continuous-learning-v2 description Instinct-based learning system that observes sessions via hooks, creates atomic instincts with confidence scoring, and evolves them into skills/commands/agents. v2.1 adds project-scoped instincts to prevent cross-project contamination. Use when capturing lessons from a session, managing instincts, or promoting them into skills, commands, or agents. metadata {"version":"2.1.0","origin":"ECC"} 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 ( ${XDG_DATA_HOME:-~/.local/share}/ecc-homunculus/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: --- 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: CLAUDE_PROJECT_DIR env var (highest priority) -- honored as an explicit override even when the directory is not a git repo (hashed by its absolute path) git remote get-url origin -- hashed to create a portable project ID (same repo on different machines gets the same ID) git rev-parse --show-toplevel -- fallback using repo path (machine-specific) 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 ${XDG_DATA_HOME:-~/.local/share}/ecc-homunculus/projects.json maps IDs to human-readable names. Data Directory Continuous-learning-v2 stores observer data outside ~/.claude so Claude Code's sensitive-path guard does not block background instinct writes: CLV2_HOMUNCULUS_DIR when set to an absolute path $XDG_DATA_HOME/ecc-homunculus $HOME/.local/share/ecc-homunculus Existing users with data at ~/.claude/homunculus can migrate once: bash skills/continuous-learning-v2/scripts/migrate-homunculus.sh Quick Start 1. Enable Observation Hooks If installed as a plugin (recommended): No extra settings.json hook block is required. Claude Code v2.1+ auto-loads the plugin hooks/hooks.json , and observe.sh is already registered there. If you previously copied observe.sh into ~/.claude/settings.json , remove that duplicate PreToolUse / PostToolUse block. Duplicating the plugin hook causes double execution and ${CLAUDE_PLUGIN_ROOT} resolution errors because that variable is only available inside plugin-managed hooks/hooks.json entries. If installed manually to ~/.claude/skills , add this to your ~/.claude/settings.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: # Global directories mkdir -p " ${XDG_DATA_HOME:- $HOME /.local/share} /ecc-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 /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: { "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 . Observer platform support The background observer requires WSL2, Linux, or macOS. On native Windows (Git Bash / MSYS2) it starts and reports success, but the process is killed when the spawning hook exits and its Job Object closes, so no analysis ever runs — setting observer.enabled: true there is effectively a no-op (see issue #2489). observe.sh detects this on the following hook invocation and writes an explanatory warning to observer-start.log once the observer has failed to survive several times in a row. Env var Default Description ECC_OBSERVER_NOSURVIVE_WARN_AFTER 3 Consecutive non-survivals before the warning is logged File Structure ${XDG_DATA_HOME:-~/.local/share}/ecc-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