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) -- honored as an explicit override even when the directory is not a git repo (hashed by its absolute path)
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.

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

---

*Content truncated.*