Continuous Learning v2 - Everything Claude Code

The Continuous Learning v2 system automatically learns from your Claude Code sessions through atomic “instincts” — small learned behaviors with confidence scoring.

Overview

What's New in v2.1

Project-scoped instincts — React patterns stay in React projects, Python conventions in Python projects. Universal patterns (like “always validate input”) are shared globally.

v2.1 Features

Feature	v2.0	v2.1
Storage	Global only	Project-scoped + global
Scope	All instincts everywhere	Isolated by project
Detection	None	git remote URL / repo path
Promotion	N/A	Project → global (2+ projects)
Commands	4	6 (+promote/projects)
Cross-project	Contamination risk	Isolated by default

v2 vs v1 Comparison

| Feature | v1 | v2 | |---------|----|----|| | Observation | Stop hook (session end) | PreToolUse/PostToolUse hooks | | Reliability | ~50-80% | 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 |

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

Instinct Properties

Atomic

One trigger, one action. Focused and reusable.

Confidence-Weighted

0.3 = tentative, 0.9 = near certain. Evolves over time.

Domain-Tagged

code-style, testing, git, debugging, workflow, etc.

Evidence-Backed

Tracks what observations created it. Transparent learning.

How It Works

Session Activity Captured

Hooks capture every prompt and tool use (100% reliable). Project context is auto-detected from git remote.Stored in: ~/.claude/homunculus/projects/<project-hash>/observations.jsonl

Pattern Detection

Observer agent (background, Haiku) reads observations and detects:

User corrections → instinct
Error resolutions → instinct
Repeated workflows → instinct
Scope decision: project or global?

Instinct Creation

Creates/updates instincts in:

projects/<hash>/instincts/personal/ (project-scoped)
instincts/personal/ (global)

Each with confidence score (0.3-0.9).

Evolution

/evolve clusters related instincts into:

commands/ — new slash commands
skills/ — reusable workflows
agents/ — specialized subagents

Project Detection

The system automatically detects your current project:

Environment Variable (Highest Priority)

export CLAUDE_PROJECT_DIR="/path/to/project"

Git Remote URL

git remote get-url origin

Hashed to create portable project ID. Same repo on different machines gets same ID.

Git Repo Path (Fallback)

git rev-parse --show-toplevel

Machine-specific fallback.

Global Fallback

If no project detected, instincts go to global scope.

Each project gets a 12-character hash ID (e.g., a1b2c3d4e5f6). A registry at ~/.claude/homunculus/projects.json maps IDs to human-readable names.

Quick Start

1. Enable Observation Hooks

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"
      }]
    }]
  }
}

2. Initialize Directory Structure

Directories are auto-created on first use. Manual creation is optional.

# Global directories
mkdir -p ~/.claude/homunculus/{instincts/{personal,inherited},evolved/{agents,skills,commands},projects}

# Project directories auto-created when hooks run in git repos

3. Use 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 instinct counts

Commands Reference

/instinct-status

Show all instincts (project-scoped + global) with confidence scores.

/evolve

Cluster related instincts into skills/commands. Suggests promotions.

/instinct-export

Export instincts. Filter by scope (project/global) or domain.

/instinct-import <file>

Import instincts from others. Control scope on import.

/promote [id]

Promote project instincts to global scope.

/projects

List all known projects and their instinct counts.

Configuration

Edit ~/.claude/skills/continuous-learning-v2/config.json:

{
  "version": "2.1",
  "observer": {
    "enabled": false,
    "run_interval_minutes": 5,
    "min_observations_to_analyze": 20
  }
}

Key	Default	Description
`observer.enabled`	`false`	Enable background observer agent
`observer.run_interval_minutes`	`5`	How often observer analyzes observations
`observer.min_observations_to_analyze`	`20`	Minimum observations before analysis

Other behavior (observation capture, instinct thresholds, project scoping, promotion criteria) is configured in instinct-cli.py and observe.sh.

File Structure

~/.claude/homunculus/
├── identity.json              # Your profile, technical level
├── projects.json              # Registry: 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)
    │   ├── 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 patterns”
File structure preferences	project	”Tests in `__tests__/`”, “Components in src/“
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”, “Handle all errors”
Tool workflow	global	”Grep before Edit”, “Read before Write”
Git practices	global	”Conventional commits”, “Small commits”

Instinct Promotion

When the same instinct appears in multiple projects with high confidence, promote to global scope.

Auto-Promotion Criteria

Same instinct ID in 2+ projects
Average confidence >= 0.8

Promote Instincts

# Promote 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

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?

v1 used skills for observation. Skills fire ~50-80% of the time based on Claude’s judgment.

Hooks fire 100% of the time, deterministically:

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/ 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

Local-First Learning

Observations stay local on your machine
Project-scoped instincts isolated per project
Only patterns (instincts) can be exported — not raw observations
No code or conversation content shared
You control what gets exported and promoted

Skill Creator — Generate instincts from repo history
Homunculus — Community project that inspired the v2 architecture
The Longform Guide — Continuous learning section

Example Workflow

Work Normally

Use Claude Code as usual. Hooks capture all activity automatically.

Check Learned Patterns

/instinct-status

Review instincts learned from your sessions.

Evolve Into Skills

/evolve

Cluster related instincts into reusable skills, commands, or agents.

Promote Universal Patterns

/promote

Move patterns that apply across projects to global scope.

Share With Team

/instinct-export

Export instincts for team members to import.

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

Get Started

Core Concepts

Platform Support

Guides

​Overview

What's New in v2.1

​v2.1 Features

​v2 vs v1 Comparison

​The Instinct Model

​Instinct Properties

Atomic

Confidence-Weighted

Domain-Tagged

Evidence-Backed

​How It Works

​Project Detection

​Quick Start

​1. Enable Observation Hooks

​2. Initialize Directory Structure

​3. Use Instinct Commands

​Commands Reference

/instinct-status

/evolve

/instinct-export

/instinct-import <file>

/promote [id]

/projects

​Configuration

​File Structure

​Scope Decision Guide

​Instinct Promotion

​Auto-Promotion Criteria

​Promote Instincts

​Confidence Scoring

​Confidence Increases When:

​Confidence Decreases When:

​Why Hooks vs Skills?

​Backward Compatibility

​Privacy

Local-First Learning

​Related Tools

​Example Workflow

Overview

v2.1 Features

v2 vs v1 Comparison

The Instinct Model

Instinct Properties

How It Works

Project Detection

Quick Start

1. Enable Observation Hooks

2. Initialize Directory Structure

3. Use Instinct Commands

Commands Reference

Configuration

File Structure

Scope Decision Guide

Instinct Promotion

Auto-Promotion Criteria

Promote Instincts

Confidence Scoring

Confidence Increases When:

Confidence Decreases When:

Why Hooks vs Skills?

Backward Compatibility

Privacy

Related Tools

Example Workflow