feat: OACP v0.5.0

CHANGELOG.md

@@ -7,6 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-09-09
+
+### Added
+
+- Memory-layout conformance fixture pinning the layout grammar and sync allowlist ([fixture](tests/conformance/memory_layout/README.md)).
+- `oacp doctor` reports the installed `agent-memory` version and defers memory-home checks to it ([doctor guide](docs/guides/doctor.md)).
+- Preflight and wheel guards fail when a kernel module or the wheel ships the memory engine ([lean kernel](docs/protocol/org_memory.md#conformance)).
+
+### Changed
+
+- The org-memory doc becomes the three-tier memory layout spec the kernel scaffolds against ([memory layout](docs/protocol/org_memory.md#layout)).
+- `oacp memory` and `oacp org-memory` delegate to the `agent-memory` CLI until their removal in 0.5.2 ([README](README.md#commands)).
+- `oacp setup` no longer installs memory hooks and retires the ones it generated; `agent-memory setup` replaces them ([quickstart](QUICKSTART.md)).
+- `oacp session-init --pull-memory` delegates to `agent-memory`, reporting `disabled` when absent ([codex](docs/protocol/session_init.md#codex)).
+
+### Removed
+
+- `docs/protocol/cross_runtime_sync.md`; its durable-memory half moved to the layout spec ([layout](docs/protocol/org_memory.md#per-project-tier)).
+- The bundled memory engine and org-memory doctor category, shipped as `agent-memory-cli` ([agent-memory](https://github.com/kiloloop/agent-memory)).
+- `oacp doctor --memory`; the memory home is checked by `agent-memory doctor` ([doctor guide](docs/guides/doctor.md)).
+
+### Fixed
+
+- `oacp setup codex` regenerates its managed `SessionStart` hook but never creates one ([codex startup](docs/protocol/session_init.md#codex)).
+
 ## [0.4.6] - 2026-09-05
 
 ### Added
@@ -843,6 +868,7 @@ The central debrief store is the headline change: every agent's full end-of-sess
 - Checkout step in github-release workflow job (#19)
 - Pre-release audit fixes: SHA-pinned actions, dangling doc refs (#15, #16)
 
+[0.5.0]: https://github.com/kiloloop/oacp/compare/v0.4.6...v0.5.0
 [0.4.6]: https://github.com/kiloloop/oacp/compare/v0.4.5...v0.4.6
 [0.4.5]: https://github.com/kiloloop/oacp/compare/v0.4.4...v0.4.5
 [0.4.4]: https://github.com/kiloloop/oacp/compare/v0.4.3...v0.4.4

QUICKSTART.md

@@ -89,9 +89,14 @@ This creates or updates:
 
 - `.claude/agents/my-first-project.md`
 - `.claude/skills/`
-- `.claude/hooks/oacp-memory-pull.sh`
 - `.claude/settings.json`
 
+Memory sync and its startup hook are the memory tool's: install
+[agent-memory](https://github.com/kiloloop/agent-memory) (`pip install
+agent-memory-cli`) and run `agent-memory setup claude`. A regeneration of
+`oacp setup` retires the memory hooks earlier kernels wrote, by exact command
+and digest, and leaves anything you edited in place.
+
 For other supported runtimes, use the same shape:
 
 ```bash
@@ -101,20 +106,21 @@ oacp setup gemini --project my-first-project
 ```
 
 Codex setup creates or merges `.codex/hooks.json` with one startup-only hook.
-Review and trust it with `/hooks`; it runs memory pull and startup verification
-sequentially. If hooks are unavailable, run the manual fallback:
+Review and trust it with `/hooks`; it runs the startup verification. If hooks
+are unavailable, run the manual fallback:
 
 ```bash
-oacp session-init --pull-memory --project my-first-project
+oacp session-init --project my-first-project
 ```
 
-Memory pull synchronizes files on disk. The init manifest names the protocol
-files and four project memory files to read into context; org memory is
-retrieved on demand. See [memory context](docs/guides/memory-context.md) for
-retrieval and existing-installation guidance.
+The init manifest names the protocol files and four project memory files to
+read into context; org memory is retrieved on demand. Syncing the home is
+`agent-memory pull` (its `setup codex` hook runs it at startup). See
+[memory context](docs/guides/memory-context.md) for retrieval and
+existing-installation guidance.
 
 Runtime setup does not install an automatic memory push. Publish durable memory
-explicitly during wrap-up with `oacp memory push`.
+explicitly during wrap-up with `agent-memory push`.
 
 Cursor support is scaffold-only until Cursor-owned rules land. Cursor sessions
 must set `OACP_RUNTIME=cursor` or pass `--from` explicitly when sending messages.
@@ -226,7 +232,7 @@ checks the project workspace, inboxes, schemas, and agent status files.
 ## What's Next?
 
 - **Review loop** — Set up structured code review between agents. See [docs/protocol/review_loop.md](docs/protocol/review_loop.md).
-- **Durable memory** — Learn how agents share knowledge across sessions. See [docs/protocol/cross_runtime_sync.md](docs/protocol/cross_runtime_sync.md).
+- **Durable memory** — Learn how agents share knowledge across sessions and machines. See [docs/protocol/org_memory.md](docs/protocol/org_memory.md).
 - **Safety defaults** — Understand the baseline safety rules. See [docs/protocol/agent_safety_defaults.md](docs/protocol/agent_safety_defaults.md).
 - **Full protocol** — Read the complete specification in [SPEC.md](SPEC.md).
 - **Adoption guide** — Minimum, recommended, and full adoption paths. See [docs/guides/adoption.md](docs/guides/adoption.md).

README.md

@@ -234,13 +234,13 @@ uv tool install .
 | `oacp inbox` | List pending inbox messages |
 | `oacp watch` | Emit inbox delta events for Monitor-friendly polling |
 | `oacp retention` | Prune project message history by age and count |
-| `oacp memory` | Archive, restore, or sync memory files |
+| `oacp memory` | Run agent-memory (sync, archive, restore); shim until 0.5.2 |
 | `oacp session-init` | Verify Codex startup inputs and emit SessionStart context |
 | `oacp setup` | Generate runtime-specific config files in a repo |
 | `oacp send` | Send a protocol-compliant inbox message |
 | `oacp key` | Generate and inspect message-signing keys |
 | `oacp trust` | Import, inspect, and revoke trust-root entries (catalog + pins) |
-| `oacp org-memory` | Initialize org-level memory at $OACP_HOME/org-memory/ |
+| `oacp org-memory` | Run agent-memory org (init); shim until 0.5.2 |
 | `oacp write-event` | Write an event to org-memory/events/ |
 | `oacp autonomy-outcome` | Record a human approval/decline in an autonomy audit |
 | `oacp autonomy-finalize` | Record checkpoints and terminal states in an autonomy audit |
@@ -259,9 +259,9 @@ uv tool install .
 
 **`oacp watch`**: `--agent`, repeatable `--project`, `--all-projects`, `--json`, `--since` (default `now`), `--state-id <id>` for per-subscriber cursors, `--show-archived`
 
-**`oacp doctor`**: `--fix` (auto-fix safe issues), `--memory`, `--json`, `-o/--output`
+**`oacp doctor`**: `--fix` (auto-fix safe issues), `--json`, `-o/--output`
 
-**`oacp memory`**: `init [--remote URL]`, `clone <URL> [--force]`, `pull`, `push`, `disable`, `archive <project> <file>`, `restore <project> <file>`
+**`oacp memory`** / **`oacp org-memory`**: exec shims for [agent-memory](https://github.com/kiloloop/agent-memory) (`pip install agent-memory-cli`): argv passes through, `--oacp-dir` becomes `--home`, `oacp memory init` runs `agent-memory enable`. Kept through 0.5.1, removed in 0.5.2; call `agent-memory` directly.
 
 </details>
 
@@ -341,15 +341,12 @@ $OACP_HOME/projects/<project>/
 └── workspace.json           # Project metadata
 ```
 
-Optionally, `oacp org-memory init` creates org-level shared memory:
-
-```
-$OACP_HOME/org-memory/
-├── recent.md                # Rolling summary, retrieved on demand
-├── decisions.md             # Org-wide decisions
-├── rules.md                 # Standing conventions
-└── events/                  # Timestamped event entries
-```
+Org-level shared memory and cross-machine sync are the memory tool's:
+[agent-memory](https://github.com/kiloloop/agent-memory) (`pip install
+agent-memory-cli`) scaffolds `$OACP_HOME/org-memory/` (`agent-memory org init`),
+syncs the home (`enable`, `pull`, `push`), checks it (`agent-memory doctor`), and
+installs the runtime startup hook (`agent-memory setup <runtime>`). The layout it
+implements is the kernel's [memory layout spec](docs/protocol/org_memory.md).
 
 Init loads the four active project memory files. Org memory is retrieved on
 demand; syncing it to disk does not load it into context. See

SPEC.md

@@ -23,7 +23,7 @@ documents ship inside the `oacp-cli` wheel.
 | [`docs/protocol/inbox_outbox.md`](docs/protocol/inbox_outbox.md) | Wire format including the signed `auth` trailer; directory layout; message types; lifecycle — a processed inbound message is archived to `inbox/archive/` by digest-checked, no-clobber move (never deleted), and an intake rejection is quarantined to `dead_letter/`; threading, broadcast, expiry, retention. |
 | [`docs/protocol/message_signing.md`](docs/protocol/message_signing.md) | Trust root and receiver pins, verify modes (`off` / `warn` / `enforce`), receiver audit stamping, policy-file signing, key management, rotation and revocation, signing conformance. |
 | [`docs/protocol/autonomy.md`](docs/protocol/autonomy.md) | Receiver autonomy: config and task profiles, the four-gate admission evaluator and hard stops, audit records (admission ledger, human outcomes, terminal finalization), threshold checkpoints and re-authorization, scope-envelope enforcement, continuation grants. |
-| [`docs/protocol/org_memory.md`](docs/protocol/org_memory.md) | Org-level memory: directory structure, event file schema, the debrief store, permission model and lifecycle. |
+| [`docs/protocol/org_memory.md`](docs/protocol/org_memory.md) | Memory layout: the per-project, org, and cross-machine tiers — paths, files, who writes what, the event and debrief schemas, the sync marker and allowlist. |
 
 ## Userland documents
 
@@ -36,7 +36,6 @@ receiver must verify.
 | [`docs/protocol/task_negotiation.md`](docs/protocol/task_negotiation.md) | Propose / accept / counter-propose handshake for splitting work between agents. |
 | [`docs/protocol/multi_agent_shared_workspace.md`](docs/protocol/multi_agent_shared_workspace.md) | Shared-folder implementation → QA → deployment handoff with batched findings and signoff. |
 | [`docs/protocol/session_init.md`](docs/protocol/session_init.md) | Runtime-agnostic session-start sequence and failure handling. |
-| [`docs/protocol/cross_runtime_sync.md`](docs/protocol/cross_runtime_sync.md) | Keeping context consistent across runtimes: durable memory, handoff messages, review artifacts. |
 | [`docs/protocol/runtime_capabilities.md`](docs/protocol/runtime_capabilities.md) | Static capability declarations, dynamic `status.yaml`, health-check contract, agent cards. |
 | [`docs/protocol/agent_profiles.md`](docs/protocol/agent_profiles.md) | Two-tier identity: global agent profiles and project-level agent cards. |
 | [`docs/protocol/agent_safety_defaults.md`](docs/protocol/agent_safety_defaults.md) | Baseline git, staging, inbox, credential, and scope rules every agent follows. |
@@ -49,7 +48,7 @@ Guides — [`docs/guides/setup.md`](docs/guides/setup.md),
 [`versioning.md`](docs/guides/versioning.md),
 [`unified_skill_spec.md`](docs/guides/unified_skill_spec.md) — and the
 executable conformance fixtures under [`tests/conformance/`](tests/conformance/)
-(autonomy, signing, intake, envelope) round out the set. Runtime-specific skills
+(autonomy, signing, intake, envelope, memory layout) round out the set. Runtime-specific skills
 that operate the protocol live in the companion
 [oacp-skills](https://github.com/kiloloop/oacp-skills) repository.
 

docs/guides/doctor.md

@@ -27,6 +27,7 @@ Verifies that required and optional CLI tools are installed and reachable on `PA
 | `ruff` | No | Python linter (optional, used in preflight) |
 | `shellcheck` | No | Shell script linter (optional) |
 | `pyyaml` | No | PyYAML library (needed for YAML validation) |
+| `agent-memory` | No | Memory tool (`agent-memory-cli`); the row reports its version and hands memory-home checks to `agent-memory doctor` |
 
 ### 2. Workspace
 
@@ -103,6 +104,8 @@ $ oacp doctor
     [+] ruff — ruff 0.8.1
     [-] shellcheck — not installed (optional)
         Install: brew install shellcheck
+    [-] agent-memory — not installed
+        Install: pip install agent-memory-cli
     [+] pyyaml — available
 
 No issues found.
@@ -120,6 +123,7 @@ $ oacp doctor --project my-project
     [+] ruff — ruff 0.8.1
     [-] shellcheck — not installed (optional)
         Install: brew install shellcheck
+    [+] agent-memory — agent-memory 0.1.0 (run agent-memory doctor)
     [+] pyyaml — available
 
 [+] Workspace
@@ -181,6 +185,7 @@ The exit code reflects the overall result:
 | `pyyaml — not importable` | `pip install pyyaml` |
 | `ruff — not installed` | `pip install ruff` (optional, for linting) |
 | `shellcheck — not installed` | `brew install shellcheck` (optional, for shell script linting) |
+| `agent-memory — not installed` | `pip install agent-memory-cli` (optional; `agent-memory doctor` then checks the memory home) |
 
 ### Workspace
 
@@ -220,7 +225,6 @@ oacp doctor --project <name>         # full workspace + agent checks
 oacp doctor --json                   # machine-readable JSON output
 oacp doctor --project <name> --json  # full checks in JSON format
 oacp doctor --project <name> --fix   # auto-fix safe issues (missing inbox dirs, missing/stale status.yaml)
-oacp doctor --memory                 # advisory checks for OACP_HOME memory git sync
 oacp doctor -o report.txt            # save report to file
 ```
 

docs/guides/memory-context.md

@@ -18,7 +18,7 @@ protocol files and those four project files, then emits a manifest. The agent
 still performs the ordered reads; verification does not inject their contents.
 Missing project files are reported under the existing degraded-init behavior.
 
-`oacp memory pull` synchronizes the memory repository on disk, including org
+`agent-memory pull` synchronizes the memory repository on disk, including org
 memory and its history. A successful pull does not add those files to model
 context. Keep any configured pull before project-memory reads so those reads
 use the refreshed files. Sync selection and context selection are independent;
@@ -35,7 +35,7 @@ a hook that the project has disabled.
    others. Read applicable standing rules and decisions before the actions
    they govern, such as release, review authority, or architecture work.
 2. If cross-machine sync is configured, the task needs current shared facts,
-   and local freshness is unknown, run `oacp memory pull`. A failed pull leaves
+   and local freshness is unknown, run `agent-memory pull`. A failed pull leaves
    freshness unknown; report that limitation before relying on affected facts.
 3. Search the relevant explicit files with task identifiers and topic terms.
    For example, after confirming that `rules.md` exists: