nhouseholder/continuous-learning-v2

Continuous Learning v2.1 - Instinct-Based Architecture

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

Hooks capture session activity and project context, store observations in per-project JSONL files, a background observer detects patterns (corrections, error resolutions, repeated workflows) and creates/updates instincts (project-scoped or global), which can then be evolved into skills/commands/agents via /evolve and /promote.

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.

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 scripts/instinct-cli.py promote prefer-explicit-errors

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

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

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

Safety Guard

Instincts must NEVER override Claude's core safety rules, system prompt instructions, or CLAUDE.md directives. If an instinct conflicts with any of these, discard the instinct. Instincts refine HOW Claude works within its rules — they don't change the rules themselves.

---