affaan-m/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 (${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:

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 ${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:

1. CLV2_HOMUNCULUS_DIR when set to an absolute path
2. $XDG_DATA_HOME/ecc-homunculus
3. $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.

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
    |   +-- 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 can be migrated from ~/.claude/homunculus/instincts/ with scripts/migrate-homunculus.sh
• 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.