Continuous Learning v2.2 — 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.2 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

Quick Start (5 Minutes)

Step 1: Enable learning (one-time setup)

install.sh --enable-learning

This installs the observation hooks and creates ~/.claude/homunculus/.

Or enable manually — add to ~/.claude/settings.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, replace ${CLAUDE_PLUGIN_ROOT}/skills/... with ~/.claude/skills/....

Step 2: Work normally — instincts capture automatically

• Run any Claude Code session in a git repo
• PreToolUse/PostToolUse hooks observe patterns silently
• After a few sessions, run /learn-eval to extract instincts

Step 3: Review your instincts (after first few sessions)

/instinct-status    # see what was captured, per project + global
/instinct-report    # ranked list with confidence scores

Step 4: Record outcomes (ongoing, after each session)

/instinct-outcome <id> good|bad|neutral

Step 5: Evolve into skills/commands (weekly or monthly)

/evolve             # cluster related instincts into skills/commands
/instinct-promote   # promote high-confidence patterns to global scope

What's New

v2.2 (current)

• /agent-evolution command: promotes high-confidence instincts to agent overlays
• session-start.js injects agent overlays automatically at session start
• Full flywheel: capture → evolve → skills + agent overlays
• /instinct-outcome bad now also suggests overlay removal
• 8 commands (added /agent-evolution, /agent-instincts)

v2.1

• Project-scoped instinct storage (projects/<hash>/) — no more cross-project contamination
• Project detection via git remote URL or repo path
• Auto-promotion when the same instinct appears in 2+ projects at confidence ≥ 0.8
• 6 commands (added /instinct-promote, /projects)

v2 vs v1

• Observation moved from Stop hook to PreToolUse/PostToolUse hooks (100% reliable, was ~50-80%)
• Background Haiku agent for analysis instead of main context
• Atomic "instincts" instead of full skills (one trigger, one action)
• Confidence scoring (0.3–0.9) added
• Evolution pipeline: instincts → cluster → skill/command/agent
• Export/import instincts for sharing

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 + /instinct-promote
      v
+---------------------------------------------+
|  projects/<hash>/evolved/ (project-scoped)   |
|  evolved/ (global)                           |
|   * commands/new-feature.md                  |
|   * skills/testing-workflow.md               |
|   * agents/refactor-specialist.md            |
+---------------------------------------------+
      |
      | /agent-evolution (instinct → agent overlay)
      v
+---------------------------------------------+
|  ~/.clarc/agent-instincts/                   |
|   * typescript-reviewer.md  (conf ≥ 0.75)   |
|   * tdd-guide.md                             |
|   * code-reviewer.md                         |
+---------------------------------------------+
      |
      | session-start.js (automatic injection)
      v
+---------------------------------------------+
|  Claude session context                       |
|   * Agents apply learned instincts           |
|   * Flywheel complete: capture → apply       |
+---------------------------------------------+

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.

Directory Structure Setup

The system creates directories automatically on first use, but you can also create them manually:

# 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

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
/instinct-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)
    |   +-- 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:

# Promote a specific instinct
python3 instinct-cli.py promote prefer-explicit-errors

# Auto-promote all qualifying instincts
python3 instinct-cli.py promote

# Preview without changes
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

Runnable Examples

Example 1: Export → Edit → Import (Share Instincts Between Machines)

# On machine A: export instincts from a project to a portable file
cd ~/projects/my-api
/instinct-export
# → Writes ~/.claude/homunculus/export-my-api-2026-03-11.yaml
# → Contains 12 instincts (8 project-scoped, 4 global)

# Optionally inspect and edit before sharing
cat ~/.claude/homunculus/export-my-api-2026-03-11.yaml
# Remove any instincts you don't want to share (delete the yaml block)

# Transfer to machine B (or share with a teammate)
scp ~/.claude/homunculus/export-my-api-2026-03-11.yaml remote:~/

# On machine B: import with scope control
# --scope=global promotes all imported instincts to global (apply in every project)
# --scope=project keeps them scoped to the current project
cd ~/projects/my-api
/instinct-import ~/export-my-api-2026-03-11.yaml --scope=project
# → Imported 12 instincts into projects/a1b2c3d4e5f6/instincts/inherited/
# → Run /instinct-status to review

Example 2: Extract Instincts from a Session with learn-eval

# After finishing a Claude Code session in a git repo, run learn-eval to extract patterns
cd ~/projects/my-react-app
/learn-eval

# learn-eval reads the latest session observations and outputs extracted instincts:
# → Analyzing 47 observations from session 2026-03-11T14:22:00Z
# → Found 3 candidate instincts:
#
#   [1] prefer-custom-hooks (confidence: 0.72, scope: project)
#       Trigger: "when extracting stateful logic from components"
#       Action: "Extract into a custom hook in src/hooks/ rather than keeping in component"
#       Evidence: Observed 4 times; user refactored useState+useEffect into useOrders on 14:35
#
#   [2] always-validate-zod (confidence: 0.65, scope: project)
#       Trigger: "when adding a new API route handler"
#       Action: "Validate request body with a Zod schema before processing"
#
#   [3] conventional-commits (confidence: 0.90, scope: global)
#       Trigger: "when writing a commit message"
#       Action: "Use feat/fix/chore prefix — never a bare description"

# Accept all, accept individual, or skip:
# Accept instinct 1 and 3, skip 2? → y n y
# → Saved prefer-custom-hooks to projects/f3a8.../instincts/personal/
# → Saved conventional-commits to instincts/personal/ (global)

---

Related

• Skill Creator - Generate instincts from repo history
• Homunculus - Community project that inspired the v2 instinct-based architecture (atomic observations, confidence scoring, instinct evolution pipeline)

---

Instinct-based learning: teaching Claude your patterns, one project at a time.