ai-learning

name	ai-learning
description	Instinct-based learning system for Codex. Manual-first: explicit capture and analysis baseline, with optional background observer.
version	2.1.0

AI Learning v2.1

An instinct-based learning system for Codex that turns repeated behavior into small reusable instincts with confidence scoring, project scoping, and optional evolution into larger assets.

v2.1 adds project-scoped instincts so project-specific patterns stay local while broader workflow and security patterns can still be shared globally.

When To Activate

• Reviewing or capturing reusable workflow patterns in Codex
• Running explicit Codex learning passes
• Reviewing instinct confidence, scope, export, import, or promotion
• Running weekly retrospectives to find automation candidates
• Deciding whether repeated work should become a skill, command, script, or MCP-backed integration

Codex Model

Codex is manual-first.

• Global MDT state lives under ~/.codex/mdt/homunculus/
• Explicit/manual capture is the baseline
• Explicit/manual analysis is the baseline
• Weekly retrospectives are part of the baseline
• The optional external observer only automates background analysis after observations already exist — it is OFF by default
• Codex does not use hook-style automatic capture

To opt in to the background observer, run:

mdt learning observer run

Or edit config.json and set observer.enabled to true.

What's New in v2.1

Feature	v2.0	v2.1
Storage	Global (~/.codex/mdt/homunculus/)	Project-scoped (<project-id>/ under homunculus)
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

v2 introduced instinct-sized learning units, confidence-weighted evidence, observer-assisted analysis, and project-aware storage and evolution paths.

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: "my-react-app-a1b2c3d4"
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 or global

Shared Learning Flow

Session activity
      |
      | explicit/manual capture
      v
<project-id>/observations.jsonl
      |
      | optional observer or explicit analysis
      v
pattern detection
      |
      | creates / updates
      v
<project-id>/instincts/personal/
instincts/personal/ (global)
      |
      | evolve / promote
      v
<project-id>/evolved/
evolved/ (global)

Project Detection

The system detects project context in this order:

1. explicit project/config environment variables such as CLAUDE_PROJECT_DIR or tool-agnostic MDT_PROJECT_ROOT
2. git remote URL when available
3. git repo root fallback when no remote is available
4. cwd-scoped fallback when no git-backed project can be identified

Project IDs use the current runtime contract:

• Remote available → <repo-name>-git — stable across re-clones of the same origin
• Git repo, no remote → <basename>-<md5(path)> — path-anchored local fallback
• No git project → <basename>-<md5(path)> using the current cwd instead of collapsing into a global project

Only git is currently detected; other VCS systems are in the backlog. A registry file at ~/.codex/mdt/homunculus/projects.json maps IDs to absolute paths, remotes, and human-readable names.

Quick Start

Codex Explicit Workflow

Use the explicit mdt workflow:

mdt learning status

Then capture a concise session summary:

mdt learning capture < summary.txt

Run an explicit analysis pass:

mdt learning analyze

Run a weekly retrospective for one ISO week:

mdt learning retrospective weekly --week 2026-W11

This writes Codex project learning state under ~/.codex/mdt/homunculus/<project-id>/....

Installed Codex-root equivalent if mdt is not on PATH:

node ~/.codex/mdt/scripts/mdt.js learning status
node ~/.codex/mdt/scripts/mdt.js learning capture < summary.txt
node ~/.codex/mdt/scripts/mdt.js learning analyze
node ~/.codex/mdt/scripts/mdt.js learning retrospective weekly --week 2026-W11

Codex baseline:

• sparse, explicit capture
• explicit/manual analysis
• explicit weekly retrospectives
• optional external observer for background analysis only (disabled by default)

Commands And Workflows

The instinct workflows are:

• status
• evolve
• export
• import
• promote
• projects
• weekly

For Codex, these are explicit mdt workflow entrypoints.

mdt learning CLI Reference

Command	Description
mdt learning status	Show current learning state, observation count, instinct count
mdt learning capture	Capture a session summary (reads from stdin)
mdt learning analyze	Run explicit analysis pass on accumulated observations
mdt learning retrospective weekly --week YYYY-Www	Generate a weekly retrospective
mdt learning observer run	Start the optional background observer (opt-in)
mdt learning observer stop	Stop the background observer

Instinct Commands

Command	Description
mdt instinct status	Show all instincts with confidence scores
mdt instinct evolve	Evolve high-confidence instincts into skills/commands/agents
mdt instinct export	Export instincts to a portable format
mdt instinct import	Import instincts from a file or Skill Creator
mdt instinct promote	Promote project-scoped instincts to global scope
mdt instinct projects	List all known projects with instinct counts

Configuration

Edit config.json to control the optional observer. The default has the observer disabled — this is the recommended baseline for Codex:

{
  "version": "2.1",
  "observer": {
    "enabled": false,
    "run_interval_minutes": 5,
    "min_observations_to_analyze": 20,
    "tool": null,
    "models": {
      "claude": "haiku",
      "cursor": "auto"
    },
    "commands": {
      "claude": "claude",
      "cursor": "agent"
    }
  }
}

To enable the observer, set "enabled": true in config.json, or run mdt learning observer run directly.

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
observer.tool	null	Force a specific native observer runner where supported
observer.commands.*	tool default	Override the native CLI command for supported observer runners

Notes:

• all scripts are Node.js .js
• Codex observer support is a separate opt-in layer, not the baseline
• the observer reads and writes under ~/.codex/mdt/

Generated Candidates vs Live Skills

Continuous learning can eventually produce skill-like artifacts, but they are not all equal.

• ~/.codex/mdt/homunculus/ stores instincts, evidence, evolution outputs, and project-scoped learning state
• ~/.codex/mdt/generated/skills/learned/ is MDT-owned staging for candidate/generated skills
• ~/.codex/skills/ is the live tool-facing skill directory

Promotion/materialization is the boundary between MDT-owned state and the live tool-facing skill surface. Until a generated skill is explicitly approved and materialized, it should stay under MDT-owned state.

Weekly Retrospectives

Weekly retrospectives are intentionally low-noise.

For Codex they are part of the recommended baseline:

~/.codex/mdt/homunculus/<project-id>/retrospectives/weekly/YYYY-Www.json

The goal is not to log more activity. The goal is to highlight:

• repeated shell commands that should become scripts or custom commands
• repeated external CLI usage that may justify MCP integrations
• repeated multi-step workflows that should be documented or automated
• repeated file hotspots that suggest missing helpers

File Structure

~/.codex/
+-- AGENTS.md
+-- config.toml
+-- rules/
+-- skills/                 # live/promoted tool-facing skills
+-- mdt/
    +-- scripts/
    +-- homunculus/
    |   +-- identity.json
    |   +-- projects.json
    |   +-- observations.jsonl
    |   +-- instincts/
    |   |   +-- personal/
    |   |   +-- inherited/
    |   +-- evolved/
    |   |   +-- agents/
    |   |   +-- skills/
    |   |   +-- commands/
    |   +-- projects/
    |   |   +-- <project-id>/
    |   |       +-- observations.jsonl
    |   |       +-- observations.archive/
    |   |       +-- instincts/
    |   |       |   +-- personal/
    |   |       |   +-- inherited/
    |   |       +-- evolved/
    |   |           +-- skills/
    |   |           +-- commands/
    |   |           +-- agents/
    +-- generated/
        +-- skills/
            +-- learned/   # candidate/generated skills awaiting promotion

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 instincts can be promoted to global scope when the same pattern is seen across multiple projects with strong confidence.

Example:

node ~/.codex/skills/ai-learning/scripts/instinct-cli.js promote
node ~/.codex/skills/ai-learning/scripts/instinct-cli.js 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 with repeated consistent evidence and decreases with corrections, contradiction, or lack of reinforcement.

Manual Capture Contract

Codex is intentionally explicit and manual:

• no hook-style automatic capture
• manual capture and manual analysis are the baseline
• optional observer is analysis-only for Codex, and is OFF by default

Backward Compatibility

v2.1 remains compatible with existing instinct storage and evolved assets. Generated candidate skills should be treated as MDT-owned staging artifacts under ~/.codex/mdt/generated/skills/learned/. Live tool-facing skills should remain in ~/.codex/skills/ and only receive explicitly promoted/materialized outputs.

Privacy

• observations stay local on your machine
• project-scoped instincts are isolated by project
• only instinct patterns, not raw observations, should be exported
• you control export, import, and promotion

Related

• Skill Creator
• Homunculus
• The Longform Guide

---

Instinct-based learning: teach the tool your patterns, one project at a time.