| 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"
---
Use functional patterns over classes when appropriate.
- 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:
- explicit project/config environment variables such as
CLAUDE_PROJECT_DIR or tool-agnostic MDT_PROJECT_ROOT
- git remote URL when available
- git repo root fallback when no remote is available
- 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:
statusevolveexportimportpromoteprojectsweekly
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
Instinct-based learning: teach the tool your patterns, one project at a time.
