| name | continuous-learning |
| 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. |
| origin | ECC |
| version | 2.1.0 |
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//) |
| 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"
---
Use functional patterns over classes when appropriate.
- 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)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 ~/.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):
{
"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:
{
"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:
mkdir -p ~/.claude/homunculus/{instincts/{personal,inherited},evolved/{agents,skills,commands},projects}
3. Use the Instinct Commands
/instinct-status
/evolve
/instinct-export
/instinct-import
/promote
/projects
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.
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" |
| Error handling strategies | project | "Use Result type for errors" |
| Security practices | global | "Validate user input", "Sanitize SQL" |
| General best practices | global | "Write tests first", "Always handle errors" |
| Tool workflow preferences | global | "Grep before Edit", "Read before Write" |
| Git practices | global | "Conventional commits", "Small focused commits" |
Instinct Promotion (Project -> Global)
When the same instinct appears in multiple projects with high confidence, it's a candidate for promotion to global scope.
Auto-promotion criteria:
- Same instinct ID in 2+ projects
- Average confidence >= 0.8
How to promote:
python3 instinct-cli.py promote prefer-explicit-errors
python3 instinct-cli.py promote
python3 instinct-cli.py promote --dry-run
The /evolve command also suggests promotion candidates.
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.1 is fully compatible with v2.0 and v1:
- Existing global instincts in
~/.claude/homunculus/instincts/ still work as global instincts
- Existing
~/.claude/skills/learned/ skills from v1 still work
- Stop hook still runs (but now also feeds into v2)
- Gradual migration: run both in parallel
Privacy
- Observations stay local on your machine
- Project-scoped instincts are isolated per project
- Only instincts (patterns) can be exported — not raw observations
- No actual code or conversation content is shared
- You control what gets exported and promoted
Related
- ECC-Tools GitHub App - Generate instincts from repo history
- Homunculus - Community project that inspired the v2 instinct-based architecture (atomic observations, confidence scoring, instinct evolution pipeline)
- The Longform Guide - Continuous learning section
Instinct-based learning: teaching Claude your patterns, one project at a time.
