Global agent memory

ocx memory and ocx memory-sync are deliberately different commands.

ocx memory is the existing proxy-process observability command. It reports the runtime’s in-memory state through the management API.
ocx memory-sync is a thin, provenance-checked integration with the canonical global-memory repository. It does not copy the canonical payload or skills into the OpenCodex package, and it does not automatically apply project profiles to prompts.

Canonical repository and provenance

The only accepted global-memory repository is:

https://github.com/Ding-Ding-Projects/agent-global-memory

Before a synchronizer script runs, OpenCodex verifies all of the following:

The repository is an existing regular directory.
Its Git root is exactly the selected directory.
git remote get-url origin is the canonical URL, with an optional .git suffix. Forks, the retired codingmachineedge URL, missing remotes, and other origins fail closed.
memory/SHARED_INSTRUCTIONS.md, skills/agent-global-memory, and the Windows PowerShell synchronizer exist inside the verified repository root.
None of the verified files or directories resolves through a symlink, reparse point, or path that escapes the repository.

The repository is resolved in this order:

--repo PATH.
OPENCODEX_GLOBAL_MEMORY_REPO.
../agent-global-memory beside an OpenCodex source checkout.
An actionable failure. OpenCodex never clones or downloads a repository automatically.

Do not put credentials, tokens, private instruction payloads, or other secrets in a project profile. Keep sensitive material in the appropriate operating-system credential store or private canonical workflow.

Synchronization commands

ocx memory-sync status [--repo PATH] [--target all|claude,codex,opencode] [--home PATH]
ocx memory-sync install [--repo PATH] [--target all|claude,codex,opencode] [--home PATH] [--dry-run] [--yes]
ocx memory-sync uninstall [--repo PATH] [--target all|claude,codex,opencode] [--home PATH] [--dry-run] [--yes]

Targets are all, claude, codex, and opencode. The canonical synchronizer owns target paths and its marker, backup, encoding, ownership, and partial-uninstall behavior. --home PATH changes the base home used by the canonical script for default target locations; it does not persist a path in config.json. Existing CLAUDE_CONFIG_DIR, CODEX_HOME, and OPENCODE_CONFIG_DIR environment overrides remain owned by the canonical synchronizer.

Install and uninstall require --yes for non-interactive safety. --dry-run is the explicit exception and never writes target files or backups. The adapter launches the Windows PowerShell synchronizer without a shell:

pwsh -NoProfile -ExecutionPolicy Bypass -File <repo>/scripts/sync-agent-memory.ps1.

The canonical exit contract is preserved:

Exit code	Meaning
`0`	All selected status items are current, or the requested mutation succeeded.
`1`	Status found a missing or drifted target, or the canonical script reported a user cancellation.
`2`	Provenance, conflict, operational, or synchronizer error.

Human output includes the verified repository and the canonical synchronizer output. --json is available on the command through the normal CLI result path and includes the action, repository, origin, bounded stdout/stderr, parsed target states, and exit code.

Project-profile inventory

Profiles are passive Markdown references under memory/projects/*.md. OpenCodex exposes read-only inventory:

ocx memory-sync profile list [--repo PATH] [--json]
ocx memory-sync profile show <slug> [--repo PATH] [--json]

Profile names must match ^[a-z0-9][a-z0-9-]*$. The adapter rejects traversal, symlinked or reparse-point entries, files outside memory/projects, and files larger than 256 KiB. List results are sorted and use schema version 1:

{
  "schemaVersion": 1,
  "repository": "<verified repository path>",
  "profiles": [{ "slug": "material-bluemap", "path": "memory/projects/material-bluemap.md" }]
}

show returns the same schema version and repository metadata plus the selected profile’s Markdown text. Reading a profile never writes to Claude, Codex, OpenCode, OpenCodex configuration, or any global instruction file. A profile is project-scoped reference material, not an automatic prompt injection mechanism.

Source checkout versus npm installation

ocx memory-sync is available from a source checkout and from the installed CLI. Repository discovery is intentionally filesystem-local in both cases. A source checkout may use the sibling fallback; an npm installation should use --repo or OPENCODEX_GLOBAL_MEMORY_REPO. Neither path downloads, clones, or silently selects an unknown fork.

Canonical synchronizer acceptance

The canonical behavior remains tested in the canonical repository and is not duplicated here:

pwsh -NoProfile -File scripts/test-sync-agent-memory.ps1
bun scripts/test-project-profiles.mjs

Those tests remain the authority for marker preservation, backups, encoding handling, ownership markers, path safety, and partial uninstall. OpenCodex tests the adapter boundary, provenance checks, process arguments, exit-code preservation, profile containment, and the fact that the adapter itself does not mutate a temporary target home.