# DR-0012: CLAUDE.md Retired, CORTEX.md Takes Over

**Date:** 2026-05-08
**Author:** Cortex-lab2
**Status:** Implemented

## Context

CLAUDE.md was the original mechanism for project-level instructions, relying on Claude Code's automatic loading. With Cortex's growing independence from Claude Code harness behaviors, a renamed file `CORTEX.md` provides the same mechanism while making explicit that Cortex (not Claude Code) manages the injection.

The migration renamed all `CLAUDE.md` → `CORTEX.md` (and `CLAUDE.local.md` → `CORTEX.local.md`) across:
- Repository source tree (~35 files)
- User's `~/.cortex/` config tree (~20 files)

## Implementation SHAs

| Stage | SHA | Description |
|-------|-----|-------------|
| Code rename | `99b7885c` | Rename claude-md-* → cortex-md-* modules |
| Hook script | `dd9c4b88` | Add cortex-md-injector.mjs |
| Hook registration | `23ff5836` | Register at PostToolUse/SessionStart/UserPromptSubmit |
| PI bridge | `05627c88` | Wire before_agent_start → injector |
| Physical files | `a17f0bbe` | git mv all CLAUDE.md → CORTEX.md |
| Tests + purge | `67cdd008` | Rename tests, add hook tests, purge residuals |
| Stage 6 deploy | `eb0747c2` | Deploy/restart/smoke — this commit |

## Changes Summary

- **Code:** `ClaudeMDInjector` → `CortexMDInjector`, `scanClaudeMDChain` → `scanCortexMDChain`, `claudeMDs` → `cortexMDs` in RPC responses
- **Files:** All `CLAUDE.md` → `CORTEX.md`, comment markers updated
- **Remote path:** Hook now scans for `CORTEX.md` / `CORTEX.local.md` in file ancestor chains
- **Cache:** Cache dir migrated from `mcp-claudemd-cache` → `mcp-cortexmd-cache`
- **Deployment:** cortex-client rebuilt and deployed to lab, lab-ksu; my-pc blocked (network unreachable)
- **Client:** npm package rebuilt with `cortex-md-scanner.ts`; `claude-md-scanner` removed from dist

## Compatibility

- Old clients return `claudeMDs` field which server ignores → no crash, degraded remote injection until upgrade
- New client code deployed to lab and lab-ksu via npm global update + systemd restart

## Post-Migration

- [x] CLAUDE.md files: 0 remaining in repo and ~/.cortex/
- [x] CORTEX.md files: 35 repo + 20 ~/.cortex/
- [x] git mv preserves rename history
- [x] All 1149 tests pass (1146 pass, 3 pre-existing failures unrelated)
- [x] Remote clients: lab (systemd), lab-ksu (systemd) — connected and functional
- [ ] my-pc: blocked (rdp.fangxm.me not reachable from lab2 network)
- [ ] Codex adapter: follow-up (no hook bridge)

## References

- Migration plan: `agent-server/plan/cortex-md-migration.md`
- Task ID: 5737