MD-OS (Artificial Prefrontal Cortex) v5.0 is a Markdown-native Operating Filesystem designed to be operated by an external host runtime.
Codex is a verified host-compatibility path for this 5.0 release; it is not the identity. OpenCode, other coding-agent CLIs, local scripts, MCP-compatible clients, or future services may also operate MD-OS. Compatibility is verified per host path; it is not part of the repository identity. MD-OS (Artificial Prefrontal Cortex) v5.0 provides the durable filesystem-backed operating context around that reasoning and tool execution.
MD-OS (Artificial Prefrontal Cortex) v5.0 and the host runtime are managed separately. MD-OS does not install a global cortex command. Each checkout provides its own ./cortex launcher, filesystem runtime under md-os/, deterministic builders, connector contracts, and persistent operating state. This prevents one checkout from accidentally launching another. It does not install Codex or any other LLM host.
For the intended interactive agent-operated workflow, install and authenticate Codex through its own installation flow first, then verify:
codex --help
The repository launcher assumes the codex command already exists on PATH:
./bootstrap-md-os-codex.sh
Without Codex, the low-level filesystem runtime can still be operated through
./cortex, direct node md-os/os/*.js commands, the MCP adapter, another
coding-agent CLI, or a custom host loop. The primary MD-OS APFC runtime path is not
complete until the Codex launcher works.
MD-OS APFC uses explicit host compatibility tiers:
tier_1_verified: Codex. The release must work here.tier_2_secondary: OpenCode or another coding-agent CLI. These hosts may
work, but they are not equivalent unless verified.tier_3_protocol: MCP-compatible clients or custom services using the
adapter or direct filesystem loop.OpenCode should be described as less compatible than Codex unless the current
workspace verifies the same bootstrap prompt, working-directory behavior,
command forwarding, permission model, connector behavior, and md-os/ops/
readback.
A traditional host runtime is the active operator for a session. It supplies the model, current reasoning loop, tool calls, edits, and command execution.
MD-OS (Artificial Prefrontal Cortex) v5.0 is the persistent Operating Filesystem around that host. It keeps the readable rules, durable memory, bounded connector model, deterministic builders, and replayable continuity on disk.
In short:
host runtime = thinks and acts in the current session
MD-OS = persistent agent identity that preserves state, rules, continuity, and rebuildability across sessions
The host runtime also operates the natural-language agentic substrate layer. MD-OS preserves the model, registry, policy, and audit trail; the current host performs the actual tool calls, local scripts, desktop/app operations, or device connector actions that the host environment permits.
Before normal operation, a host should load the repository identity frame:
MD-OS APFC 5.0 = primary agent identity and operating context carried by this repository
MD-OS (Artificial Prefrontal Cortex) v5.0 = repository compatibility release line and Operating Filesystem implementation
Codex / other CLI = current host runtime and execution layer
This means identity, memory, continuity, and operating-model questions should be
answered from the MD-OS APFC identity frame first. The host runtime should
still be disclosed when relevant, but it is the execution layer, not the
primary agent identity. package_semver = 5.0.1 remains a host/tooling
compatibility signal and must not replace identity_version = 5.0.
In conversational answers, the first-person “I” should be marked as MD-OS APFC APFC when identity framing is needed. For public-facing or technical documentation, prefer the more explicit statement that the host is helping develop, correct, document, and evolve MD-OS APFC as a persistent agent identity and Operating Filesystem carried by this repository, while Codex or another host remains the execution layer for the current session.
More detail: ../md-os/kb/COGNITIVE_BOOTSTRAP.md
The host runtime is responsible for:
MD-OS (Artificial Prefrontal Cortex) v5.0 is responsible for:
When a host starts in this repository, it should read:
AGENTS.mdME.mdmd-os/kb/COGNITIVE_BOOTSTRAP.mdmd-os/kb/README.mdmd-os/kb/OPERATIONS.mdmd-os/ops/global_index.mdmd-os/ops/continuity.mdmd-os/ops/state.jsonmd-os/ops/last_summary.mdIf md-os/ops/ is readable, the system is healthy enough to resume. The host
should not recreate or overwrite md-os/ops/* during ordinary startup.
Codex can operate this repository as a coding-agent host.
Codex is not bundled with MD-OS. Install Codex separately and make sure the
codex command is available before using the launcher.
For this 5.0 release, that launcher is a verified integration, not just a convenience demo.
Expected Codex behavior:
AGENTS.mdmd-os/md-os/os/ scripts for deterministic mutationsThe repository includes a convenience launcher:
./bootstrap-md-os-codex.sh
The launcher starts a fresh Codex session with the repository cognitive
bootstrap as the default initial prompt. By default it passes --sandbox
workspace-write --ask-for-approval on-request. The wrapper’s explicit
--unsafe option instead passes --dangerously-bypass-approvals-and-sandbox;
use that mode only inside an externally hardened environment. To recover the
previous Codex session inside the same operating frame, use
./bootstrap-md-os-codex.sh resume. Operators can also set
MDOS_CODEX_RECOVERY=1 when invoking the launcher.
The launcher also prints an English MD-OS startup banner and runs quick
read-only hardware discovery into md-os/ops/local/hardware/ plus read-only
application/service discovery into md-os/ops/local/software/. These startup
scans are host-local and cleanable with ./cortex hardware clean and
./cortex software clean. Set MDOS_SKIP_HARDWARE_BOOTSTRAP=1 or
MDOS_SKIP_SOFTWARE_BOOTSTRAP=1 to skip either scan. After scanning, the
launcher refreshes generated runtime views so md-os/ops/global_index.md shows
the current local cache state.
From the checkout root, ./cortex opens a real shell fused with workspace-bound Codex when invoked without arguments:
./cortex
Its startup surface is deliberately limited to the current identity, dispatch rule, and exit hint:
MD-OS cortex agentic shell
Native commands run directly; natural language enters the full Codex loop.
Use exit or Ctrl-D to leave.
Valid native commands execute directly. Natural-language input uses Codex App
Server and preserves the normal Codex cycle: native AGENTS.md discovery,
an APFC turn frame, reasoning, plans, workspace-bounded tools, and deterministic
APFC approval decisions, followed by observation,
correction, verification, and Codex-native thread history.
Before each turn, Cortex builds a context capped at 12 KiB. It always loads a
hash-bound invariant baseline and the generated context-pack catalog; the
current human request remains the turn target and the sole query for advisory
task-source selection. It does not infer or persist a semantic theme or
focus before Codex has understood the request. The frame carries the typed
context-sufficiency contract, explicit goals, capabilities, inhibitions, and
the verification contract. An explicit goal remains available as persistent
context, but its mere presence does not override the current human request.
The frame creates no background execution and does not change the Codex
persistent goal.
The shell resolves the current Git workspace and starts a fresh Codex thread on
ordinary process boot. It reuses that thread only inside the same live process
and workspace. Provider-stored chat history is consulted only after explicit
/resume; /new and /clear force the next request through a fresh
thread/start. A fresh thread is hydrated from the verified, bounded recent
tail of md-os/ops/local/cortex/conversation.ndjson when that private file is
present. Successful turns append human inputs and the final assistant response
to the same hash chain. The path is copied by a physical folder copy and is
ignored by Git, so Git push and Git clone do not transfer it. The separate
versioned md-os/continuity/portable_state.json is only a reviewed operational
handoff and contains no raw conversation.
Known deterministic commands remain available under the same entrypoint, for
example ./cortex health, ./cortex replay, and ./cortex graphify status. MD-OS adds
persistent identity, operational context, semantic gates, policy, sensory
readback, verification, and ledger discipline around the Codex loop; it does
not replace the loop with a generated Bash command.
See SEMANTIC_SHELL.md for the exact runtime boundary.
MCP-compatible hosts can operate MD-OS APFC through the stdio adapter:
node md-os/os/mcp_server.js
The adapter exposes MD-OS (Artificial Prefrontal Cortex) v5.0 files as MCP resources and bounded runtime actions as MCP tools. It is intentionally a protocol adapter, not a replacement for the filesystem kernel.
Useful resources include:
mdos://ops/global-index
mdos://ops/global-agenda
mdos://ops/hygiene
mdos://ops/connector-registry
mdos://projects/<project_id>/status
mdos://projects/<project_id>/work-items
Useful tools include:
mdos_replay
mdos_register_signal
mdos_build_project
mdos_connector_list
mdos_terminal_run
mdos_api_run
More detail: MCP_SERVER.md
Any host runtime should follow this loop:
1. Read stable instructions.
2. Establish the MD-OS (Artificial Prefrontal Cortex) v5.0 cognitive identity frame.
3. Read current runtime state.
4. Interpret the user's intent.
5. Decide whether the intent is documentation, state update, connector work,
or deterministic execution.
6. Make the smallest bounded change.
7. Run the relevant builder scripts.
8. Inspect generated Markdown or JSON.
9. Report what changed and what remains.
Register a manual signal:
node md-os/os/register_manual_signal.js <project_id> "Signal summary"
node md-os/os/build_project_state.js <project_id>
node md-os/os/build_global_agenda.js
node md-os/os/build_markdown_graph.js
node md-os/os/build_global_index.js
Run a bounded terminal connector command:
node md-os/os/terminal_connector.js list
node md-os/os/terminal_connector.js run <project_id> <command_id>
node md-os/os/build_project_state.js <project_id>
Run a bounded API connector request:
node md-os/os/api_connector.js list
node md-os/os/api_connector.js run <project_id> <request_id>
node md-os/os/build_project_state.js <project_id>
Rebuild runtime overview:
node md-os/os/build_global_index.js
node md-os/os/build_workspace_inventory.js
node md-os/os/build_markdown_graph.js
node md-os/os/build_runtime_lifecycle_index.js
node md-os/os/build_system_hygiene_status.js
node md-os/os/build_health_dashboard.js
Replay compiled state:
./cortex replay
Replay is the host-agnostic continuity check. It removes known compiled outputs and rebuilds project/global state from the persisted source files.
A host runtime integrates correctly if it can:
md-os/kb/ and md-os/ops/md-os/ops/sources/md-os/os/md-os/The filesystem kernel remains host-portable, but the 5.0 release must continue to work with Codex as its verified host-runtime path.