Startup project

Startup Project Memory

Load memory once at the beginning of a project-scoped task. Do nothing for ordinary conversation without a concrete project.

1. Resolve The Memory Root

The stable pointer is %USERPROFILE%\.codex\config\ai-memory-root.json. Never infer the root by scanning drives or parent folders, and never create or repair the pointer during startup.

Invoke the root resolver with a process argument array:

$configPath = Join-Path $env:USERPROFILE '.codex\config\ai-memory-root.json'
$rootArguments = @(
  '-NoProfile', '-ExecutionPolicy', 'Bypass', '-File',
  '<skill-dir>\scripts\resolve_memory_root.ps1',
  '-ConfigPath', $configPath
)
$rootResult = (& powershell.exe @rootArguments | Out-String) | ConvertFrom-Json

Accept only status: loaded. Otherwise report the exact config_path and message, then stop substantive project work. Set $memoryRoot to the returned memory_root; use that value for every later path. Do not retain a fallback root in instructions or code.

2. Load Global Rules And Memory

Read these files completely and in order:

1. <AI_MEMORY_ROOT>\AI_MEMORY_CONTRACT.md
2. <AI_MEMORY_ROOT>\GLOBAL_BEHAVIOR_INSTRUCTION.md
3. <AI_MEMORY_ROOT>\global\preferences.md
4. <AI_MEMORY_ROOT>\global\failure-patterns.md

Then enumerate every additional *.md file below <AI_MEMORY_ROOT>\global, recursively. Normalize and deduplicate paths, sort them in stable path order, and read each completely. Do not reread preferences.md or failure-patterns.md. Ignore non-Markdown files unless the contract requires them.

Before every read, verify that the target is a non-reparse regular file physically contained under $memoryRoot for the two required root files or under $memoryRoot\global for global Markdown. If any required, additional, historical, unreadable, reparse, or out-of-root file fails validation, report its exact path and stop. Do not continue with partial global rules.

3. Resolve The Canonical Project Name

Use this priority:

1. Explicit project name supplied by the user.
2. Project name or path clearly named in the current request.
3. Current repository or workspace basename.
4. Ask when evidence conflicts, is generic, or would map to a generic workspace despite a different named project.

Prefer an exact existing directory name under $memoryRoot\projects. Never treat _template as a project and never create a guessed project folder.

4. Resolve Without Writing

Invoke the project resolver with a process argument array. Pass each argument separately. Omit -WorkspacePath when empty. Otherwise pass only a fully qualified local filesystem path and never pass a URI, UNC/device path, credential, token, key, or other secret.

$arguments = @(
  '-NoProfile', '-ExecutionPolicy', 'Bypass', '-File',
  '<skill-dir>\scripts\resolve_project_memory.ps1',
  '-ProjectName', $canonicalName,
  '-MemoryRoot', $memoryRoot,
  '-Mode', 'Resolve'
)
if (-not [string]::IsNullOrEmpty($workspacePath)) {
  $arguments += @('-WorkspacePath', $workspacePath)
}
& powershell.exe @arguments

Parse the single compressed JSON result:

• loaded: continue using the reported layout version without writing.
• missing: report the canonical name and proposed path, then ask for explicit initialization approval.
• incomplete: report every missing file and ask before repair.
• error: report the exact message and stop project work.

After explicit approval for a missing project, invoke the same argument array with -Mode Initialize. Accept only created; otherwise report the returned status and stop. Initialization creates a verified v2 project from _template.

5. Load V2 Project Memory Progressively

For layout_version: 2, read these startup files completely and in order:

1. project-manifest.json
2. memory-index.md
3. handoff.md
4. working-agreement.md

Parse the manifest as JSON. Verify schema_version is 2.0, canonical_name matches, index_file is memory-index.md, and each workspace path is a fully qualified local path.

Enumerate all remaining project files in stable normalized path order, but select detail using the index and current task:

• project-brief.md for stable purpose, scope, or locations;
• decisions.md when an existing choice may govern the task;
• findings.md for prior evidence or analysis;
• session-log.md only when chronology matters;
• ai-self-evaluation.md only for operational performance or recurring collaboration issues;
• indexed topic files when relevant;
• immutable historical files last, only when needed, and never modify them.

Current decisions and handoff override historical snapshots when they conflict. For every read, require a non-reparse regular file physically contained below the resolved project root. If a startup file is missing, unreadable, reparse, malformed, or out of root, report its exact path and stop.

6. Load Legacy V1 Memory

For layout_version: 1, read completely: project-brief.md, decisions.md, findings.md, handoff.md, working-agreement.md, session-log.md, and ai-self-evaluation.md. Then read remaining Markdown in stable path order, with immutable history last. Apply the same validation. Report the legacy layout and never migrate it automatically.

7. Report Startup State

Report one concise line with status, canonical name, project-memory path, layout version, startup files loaded, deferred-detail count, and any incomplete, legacy, malformed, or stale-index warning. For v2, complete startup means the four startup files were read and remaining project files inventoried; it does not mean every detail file was read. Reading memory never authorizes a memory write.