oacp-cli 0.4.6__tar.gz → 0.5.0__tar.gz

{oacp_cli-0.4.6 → oacp_cli-0.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

{oacp_cli-0.4.6 → oacp_cli-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: oacp-cli
-Version: 0.4.6
+Version: 0.5.0
 Summary: Open Agent Coordination Protocol CLI for file-based multi-agent workflows
 Project-URL: Homepage, https://github.com/kiloloop/oacp
 Project-URL: Repository, https://github.com/kiloloop/oacp
@@ -262,13 +262,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 |
@@ -287,9 +287,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>
 
@@ -369,15 +369,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

{oacp_cli-0.4.6 → oacp_cli-0.5.0}/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).

{oacp_cli-0.4.6 → oacp_cli-0.5.0}/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

{oacp_cli-0.4.6 → oacp_cli-0.5.0}/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.
 

{oacp_cli-0.4.6 → oacp_cli-0.5.0}/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
 ```
 

{oacp_cli-0.4.6 → oacp_cli-0.5.0}/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:

{oacp_cli-0.4.6 → oacp_cli-0.5.0}/docs/protocol/message_signing.md

@@ -333,8 +333,8 @@ can never authenticate a message.
 - **Keys are per-machine and never leave `$OACP_HOME/keys/`.** They are
   never synced and never committed. The memory-sync allowlist structurally
   excludes `keys/` on the push side, and the canonical workspace
-  `.gitignore` carries an explicit `keys/` deny line that `oacp memory
-  init` and the doctor `root-gitignore` drift check propagate fleet-wide.
+  `.gitignore` carries an explicit `keys/` deny line that the memory tool
+  (`agent-memory enable`, and its doctor's drift check) propagates fleet-wide.
 - **The 0600 file keystore is the v0.4.0 floor, not the design.** Private
   key files are created `0600` under `0700` directories and loaded only
   after a mode check. The backend is pluggable by design: messages

{oacp_cli-0.4.6 → oacp_cli-0.5.0}/docs/protocol/org_memory.md

@@ -1,13 +1,124 @@
-# Org-Level Memory Protocol
+# Memory Layout Protocol
 
 ## Purpose
 
-Shared, cross-project memory for multi-agent organizations. Agents across projects read org-wide decisions, conventions, and events from a single location. Complements per-project memory (`$OACP_HOME/projects/<project>/memory/`) — does not replace it.
+Durable memory shared by every agent and runtime in an OACP home, laid out in
+three tiers:
+
+| Tier | Where | Holds |
+|---|---|---|
+| Per-project | `projects/<project>/memory/` | The four-file active working set one project's agents read at session start, plus `archive/` |
+| Org | `org-memory/` | Cross-project decisions, conventions, events, and the debrief store |
+| Cross-machine | The home as a git repository | The two storage tiers above, carried between machines by an allowlisted sync |
+
+The kernel owns this layout: the paths, the files, who writes what, the marker
+and ignore files, and the sync allowlist. `oacp init` scaffolds the per-project
+tier against it. Memory *tooling* — the org-tier scaffold, capture, recall,
+archive, the sync verbs, a memory doctor — is userland and lives in
+[`agent-memory`](https://github.com/kiloloop/agent-memory) (`agent-memory-cli`
+on PyPI), which implements this layout and links back here; this document
+names no command surface. Runtime loading mechanics stay where they are: the
+session-start read set is [Session Init](session_init.md#step-3-load-durable-memory)
+Step 3, and org-memory retrieval policy is the
+[memory context guide](../guides/memory-context.md).
+
+Lean-kernel admission: what every receiver must understand to share memory
+with another is the layout — an entry written to
+`projects/<project>/memory/decision_log.md` on one machine must be found at
+that path by every other agent and machine. Everything else about memory (what
+a good entry looks like, when to promote, how to search) is convention and
+lives in guides and skills.
+
+## Layout
+
+The complete layout, relative to the OACP home (`$OACP_HOME`). `*` stands for
+one project name; a trailing `/` marks a directory. This block is the finite
+grammar of the layout: an implementation creates nothing else and a document
+names nothing else.
+
+```oacp-memory-layout
+.gitignore
+.oacp-memory-repo
+org-memory/
+org-memory/recent.md
+org-memory/decisions.md
+org-memory/rules.md
+org-memory/events/
+org-memory/debriefs/
+projects/
+projects/*/memory/
+projects/*/memory/project_facts.md
+projects/*/memory/decision_log.md
+projects/*/memory/open_threads.md
+projects/*/memory/known_debt.md
+projects/*/memory/archive/
+projects/*/memory/.cache/
+```
+
+`<project>` follows the workspace project-name rule: any name that does not
+start with `.` and contains no `/` or `\`. Everything else in the home is not
+memory — `keys/` (the signing keystore, denied below), a project's `agents/`
+and `packets/` trees, `state/`, and any other sibling stay on the machine that
+wrote them. `.gitkeep` placeholders that scaffolding drops into empty
+directories so they survive git are scaffolding, not layout.
+
+Scaffolding creates missing entries only. A file slot that is already
+occupied — by a regular file, a directory, or a link, dangling included — is
+never rewritten and never followed. An existing directory is entered as found,
+a directory symlink included. A home that has drifted from this layout is
+reported by tooling, not silently repaired.
+
+## Per-Project Tier
+
+**Location:** `projects/<project>/memory/`, created by `oacp init <project>`
+with the rest of the project workspace.
+
+### The four files
+
+The active working set. Every runtime reads these four files, in this order, at
+session start ([Session Init](session_init.md#step-3-load-durable-memory)
+Step 3), and only verified, stable outcomes are written to them.
+
+| File | Holds | Written by |
+|---|---|---|
+| `project_facts.md` | Agent roles, repo structure, architecture, conventions | Any agent, via the project's durable-memory promotion flow |
+| `decision_log.md` | Dated decisions with rationale. Append-only: a decision is superseded by a newer entry, never edited | Any agent, via the promotion flow |
+| `open_threads.md` | Unresolved issues, blocked work, cross-agent coordination | Any agent, via the promotion flow |
+| `known_debt.md` | Verified unresolved debt that should persist across sessions | Any agent, via the promotion flow |
+
+Scaffolding writes each file once, from a template, and never overwrites one
+that exists.
+
+**Promotion flow.** Memory is written at stable points, not during work. Merge
+decisions and equivalent terminal artifacts carry a "Durable Memory Updates"
+section, and the project's promotion mechanism appends approved entries to the
+matching file, deduplicating against existing content. Raw logs, long command
+output, transcripts, and in-progress state never enter these files (see
+[Durable Memory Promotion](multi_agent_shared_workspace.md#durable-memory-promotion)).
+
+### `archive/`
+
+`projects/<project>/memory/archive/` holds files retired from the active set —
+supplementary notes a project accumulated, or an older working file replaced by
+a newer one — for historical retention. Archived files are retrieved when a
+task needs them; restoring one to `memory/` does not add it to the required
+session-start reads, which stay the four files above.
 
-## Directory Structure
+### `.cache/`
+
+`projects/<project>/memory/.cache/` is reserved for local, regenerable state
+(indexes, scratch) that tooling keeps beside the tier. It never syncs (see the
+allowlist below) and is never a session-start read.
+
+## Org Tier
+
+**Location:** `org-memory/`, beside `projects/`, created by `agent-memory org
+init`. Shared, cross-project memory: agents across projects read org-wide
+decisions, conventions, and events from a single location. It complements
+per-project memory and never replaces it.
 
 ```
-$OACP_HOME/org-memory/
+org-memory/
   recent.md           # rolling summary (~60K chars / ~15K tokens)
   decisions.md        # topical: org-wide decisions (illustrative default)
   rules.md            # topical: standing conventions (illustrative default)
@@ -33,7 +144,7 @@ budget governs. Collapse older detail into topical files or history so the
 file remains a bounded rolling summary when retrieved. This is a curation
 budget, not a requirement or allowance to load that much context at startup.
 
-## Event File Schema
+### Event File Schema
 
 ```markdown
 ---
@@ -50,7 +161,7 @@ supersedes: event/20260310-old-decision   # optional — for decisions that over
 Short description of what happened and why it matters.
 ```
 
-### Required Fields
+#### Required Fields
 
 | Field | Type | Description |
 |-------|------|-------------|
@@ -60,15 +171,15 @@ Short description of what happened and why it matters.
 | `project` | string | Originating project |
 | `type` | enum | `decision`, `event`, or `rule` |
 
-### Optional Fields
+#### Optional Fields
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `source_ref` | string | Provenance ID for dual-write reconciliation |
+| `source_ref` | string | Provenance ID for dual-write reconciliation; when the event was folded from a session debrief, the debrief-store filename stem (`<YYYYMMDD>-<agent>-<session>`) |
 | `related` | list | Cross-references to PRs, issues, or other events |
 | `supersedes` | string | Event path that this entry overrides |
 
-### File Naming
+#### File Naming
 
 Files are named `YYYYMMDD-HHMMSS-short-slug.md` where the timestamp provides sub-day ordering and the slug is a brief descriptor (lowercase, hyphen-separated).
 
@@ -84,14 +195,15 @@ per session — instead of in per-project trees. Debriefs are the full-fidelity
 session record; events remain the filtered-outcome channel. The two are
 distinct artifact classes and neither substitutes for the other.
 
-`oacp org-memory init` creates `debriefs/` (with a `.gitkeep` placeholder so
-the empty directory survives git-based sync). `oacp doctor` checks the store
-setup — directory presence, path layout, lingering staging artifacts,
+The org-tier scaffold creates `debriefs/` (with a `.gitkeep` placeholder so
+the empty directory survives git-based sync). The memory doctor checks the
+store setup — directory presence, path layout, lingering staging artifacts,
 irregular entries — and never opens debrief files: content and format
 verification belong to the writer contract (read-back at publication) and to
 git history, not to the doctor. The kernel owns only this layout and schema;
-the writer that produces debrief files is adopter tooling (for example, a
-debrief skill script) — there is no kernel subcommand for writing debriefs.
+the writer that produces debrief files is adopter tooling (for example,
+agent-memory's debrief verb) — there is no kernel subcommand for writing
+debriefs.
 
 ### Path and File Naming
 
@@ -258,47 +370,93 @@ configuration is needed.
 - Debriefs are permanent history: individual files are never rewritten (see
   Append-Only Rule); retention beyond that is adopter-defined
 
-## Integration Pattern (Cortex Reference Implementation)
-
-Cortex demonstrates the dual-pipeline pattern — same source data, two audiences. This is a reference implementation, not a protocol requirement.
-
-**Debrief step (write):**
-- Debrief → cortex inbox (existing, for human)
-- Debrief → `org-memory/debriefs/` (the canonical immutable session record — see Debrief Store)
-- Curated outcome events → `org-memory/events/` (filtered derivatives, for agents — never the raw debrief; see Curation Guard)
-- All three writes treated as a logical unit — retry/warn on partial failure
-- `source_ref` in event frontmatter matches the debrief-store filename stem (`<YYYYMMDD>-<agent>-<session>`) for reconciliation
-
-**Sync step (curate):**
-- Debriefs (read from `org-memory/debriefs/`) → SSOT + vault daily notes (existing, for human)
-- Events → topical files + `recent.md` (new, for agents)
-- Sync cross-references SSOT when curating topical files to prevent drift
-- Sync is idempotent — handles duplicates/replays via `source_ref` + `created_at_utc`
-
-**Consistency model:** Eventual, not strong. The pipelines may temporarily diverge. `source_ref` enables reconciliation against the debrief-store record. Adopter failure semantics (retryable partial failure, blocked debrief, or acceptable degraded mode) apply to the inbox and event writes; the debrief-store write is required by the Debrief Store section, and a store write that ultimately fails is a reported failure to retry, never an accepted degraded mode.
-
-## v0.2 Scope
-
-1. Format spec (directory structure, frontmatter schema, naming convention)
-2. CLI: `oacp org-memory init` (scaffold directory, including `debriefs/`) and `oacp write-event` (create event files)
-3. Agents write their full session debrief to `org-memory/debriefs/` (via adopter tooling — see Debrief Store) and curated outcome events during debrief
-4. Agents retrieve relevant sections of topical files and `recent.md` for org context on demand
-5. Coordinator maintains topical files during sync
-
-## v0.3+
+## Cross-Machine Tier
+
+Optional. A home that syncs is a plain git repository at the home root with
+one remote; the layout does not change and no server is involved. The two
+storage tiers are what syncs, selected by an allowlist; every other path in
+the home stays on the machine that wrote it. What an implementation does with
+the allowlist — commit, push, fast-forward pull, refuse to merge — is the
+tool's contract, not the kernel's: see agent-memory's
+[sync commands](https://github.com/kiloloop/agent-memory/blob/main/docs/commands.md#sync).
+
+### The marker
+
+`.oacp-memory-repo` at the home root marks a home whose memory syncs. Presence
+is the whole signal: tooling and startup hooks that pull memory check for the
+file and do nothing when it is absent, so removing it disables sync locally
+without touching the repository or its history. Its content is informational.
+The name is a compatibility contract with every existing home; keep it
+verbatim. Syncing is opt-in, so scaffolding a home never creates the marker.
+
+### The sync allowlist
+
+`.gitignore` at the home root carries the canonical allowlist, byte for byte:
+
+```gitignore
+*
+!*/
+!.gitignore
+!.oacp-memory-repo
+!org-memory/**
+!projects/*/memory/**
+projects/*/memory/.cache/
+# never sync private key material — explicit deny, wins over any future allowlist widening
+keys/
+```
 
-- Agent write access to topical files (with schema validation)
-- `recent.md` auto-generation from topical files + recent events
-- Search/discovery tooling (BM25 or similar)
-- Structured `id` field on events for cross-referencing
+Line by line:
+
+- **Deny everything, then re-allow directories** (`*`, `!*/`) so the tier
+  patterns below can reach into the tree.
+- **The synced set** is the ignore file itself, the marker, `org-memory/**`
+  in full (the debrief store included), and `projects/*/memory/**` for every
+  project.
+- **`projects/*/memory/.cache/` never syncs** — the one excluded subtree
+  inside a tier.
+- **`keys/` never syncs.** The signing keystore
+  ([key management](message_signing.md#key-management)) is denied last, after
+  every allow rule, so the deny wins even if the allowlist is widened above
+  it.
+
+### Which paths sync
+
+The allowlist is also a predicate over home-relative paths, and the predicate,
+not the ignore file, is what a sync engine trusts:
+
+- `.gitignore` and `.oacp-memory-repo` are allowed.
+- A path with any component named `keys` is denied, at any depth, whatever
+  the ignore file says.
+- A path strictly inside a tier directory (`org-memory/…`,
+  `projects/<project>/memory/…`) is allowed unless its first component below
+  the tier is one of that tier's unsynced names. The project tier excludes
+  `.cache`; the org tier excludes nothing, so `org-memory/.cache/…` syncs.
+  The tier directory itself is not a path inside it.
+- Every other path is denied.
+
+The tier directories an engine may stage are enumerated in allowlist order:
+`org-memory/` first, then each existing `projects/<project>/memory/` in
+project-name order.
+
+## Conformance
+
+The layout ships as data. `tests/conformance/memory_layout/layout.yaml`
+carries the same entry set as the Layout block above, and
+`canonical_memory_gitignore.txt` beside it is the allowlist byte for byte.
+`tests/test_memory_layout_fixture.py` holds this document, the fixture, and
+the kernel's project-tier scaffold to one another in both directions, and
+derives the allowlist's rule lines from the fixture's tiers and never-synced
+names so the two fixture files cannot disagree. An implementation vendors the
+two fixture files and asserts its own layout table, ignore text, and org-tier
+scaffold against them the same way.
 
 ## Design Rationale
 
 | Alternative | Why not |
 |---|---|
 | Single monolithic file | Wastes tokens, no progressive disclosure |
-| Events only (Codex pattern) | Optimizes for writing, weak for reading — "What's our API convention?" shouldn't require scanning 50 event files |
-| Topical only (Iris pattern) | No low-friction write path for agents — event files require only frontmatter, not schema knowledge |
+| Events only | Optimizes for writing, weak for reading — "What's our API convention?" shouldn't require scanning 50 event files |
+| Topical only | No low-friction write path for agents — event files require only frontmatter, not schema knowledge |
 | Inheritance model | Flat merge is simpler, no parent/child override complexity |
 
 The hybrid (topical + events) gives agents a fast read path (topical files) and a fast write path (events/), with coordinator curation bridging the two.

{oacp_cli-0.4.6 → oacp_cli-0.5.0}/docs/protocol/runtime_capabilities.md

@@ -173,9 +173,11 @@ The `oacp doctor` command validates environment and workspace health. Every chec
 ### Runtime startup and session telemetry
 
 Runtime-specific startup owns `status.yaml`. For Codex, `oacp setup codex`
-registers a `SessionStart` handler that runs memory pull and `oacp session-init`
-sequentially after the user reviews and trusts it with `/hooks`. The manual
-fallback is `oacp session-init --pull-memory --project <project>`.
+registers a `SessionStart` handler that runs `oacp session-init` after the user
+reviews and trusts it with `/hooks`; memory pull is the memory tool's own hook
+(`agent-memory setup codex`). Registration regenerates the managed handler only —
+an existing hooks file carrying no managed entry is never given one. The manual
+fallback is `oacp session-init --project <project>`.
 
 Memory pull synchronizes disk files. Init names the required protocol and
 project-memory reads; org-memory retrieval is on demand. See