Continuous Learning v2

An advanced learning system that turns your Claude Code sessions into reusable knowledge through atomic “instincts” - small learned behaviors with confidence scoring.

What’s New in v2.1

v2.1 adds project-scoped instincts — React patterns stay in your React project, Python conventions stay in your Python project, and universal patterns are shared globally.

Feature	v2.0	v2.1
Storage	Global (~/.claude/homunculus/)	Project-scoped (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

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

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]     |
+---------------------------------------------+

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
git rev-parse --show-toplevel — fallback using repo path
Global fallback — if no project is detected, instincts go to global scope

Each project gets a 12-character hash ID (e.g., a1b2c3d4e5f6).

Quick Start

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

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

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

Overview

Core Skills

Development Patterns

Language-Specific Skills

Advanced Skills

What’s New in v2.1

When to Activate

The Instinct Model

How It Works

Project Detection

Quick Start

Scope Decision Guide

Instinct Promotion (Project → Global)

Confidence Scoring

Why Hooks vs Skills?

​What’s New in v2.1

​When to Activate

​The Instinct Model

​How It Works

​Project Detection

​Quick Start

​Scope Decision Guide

​Instinct Promotion (Project → Global)

​Confidence Scoring

​Why Hooks vs Skills?

What’s New in v2.1

When to Activate

The Instinct Model

How It Works

Project Detection

Quick Start

Scope Decision Guide

Instinct Promotion (Project → Global)

Confidence Scoring

Why Hooks vs Skills?