feat(plugins): share Codex hook defaults

plugins/codex/README.md

@@ -38,7 +38,7 @@ verification, decision capture, and resumable checkpoints.
 | `skills/` | Codex-native Basic Memory workflows |
 | `schemas/` | Seed schemas for Codex sessions, decisions, and tasks |
 
-The hook scripts carry no logic: the brief, the checkpoint, and opt-in event
+The hook scripts carry no logic: the brief, the checkpoint, and lifecycle-event
 capture all live in the pinned Basic Memory revision behind `bm hook`. Each is
 a self-contained PEP 723 script pinned to a Basic Memory Git ref. Both refs
 are updated together with `just set-codex-hook-version <sha-or-tag>`.
@@ -69,17 +69,20 @@ Plugin installation is user-level in Codex, so one install makes the plugin
 available across projects on the same machine. Start a new Codex thread after
 installing so Codex can load the plugin skills, MCP configuration, and hooks.
 
-Each repository still needs its own `.codex/basic-memory.json` so the plugin
-knows which Basic Memory project and folders to use for that checkout. Run the
-setup skill in each repo, or create the config file shown below.
+Configuration can live at user level in `~/.codex/basic-memory.json` or at
+project level in `.codex/basic-memory.json`. User-level settings are the base;
+the nearest project file overrides only the keys it declares. `redactKeys` and
+`redactPaths` are the privacy exception: their user and project lists accumulate.
+The setup skill asks which scope to use and recommends user-level configuration
+by default.
 
 To customize how Codex writes memory, edit `skills/bm-writing/SKILL.md` in the
 plugin source. `bm-checkpoint`, `bm-decide`, and `bm-remember` all apply that
 shared skill while retaining their own schemas and evidence requirements.
 
 ## Configuration
 
-Run the setup skill, or create `.codex/basic-memory.json` in a repo:
+Run the setup skill, or create `~/.codex/basic-memory.json` for shared defaults:
 
 ```json
 {
@@ -88,24 +91,36 @@ Run the setup skill, or create `.codex/basic-memory.json` in a repo:
     "secondaryProjects": [],
     "teamProjects": {},
     "focus": "code/dev",
-    "sessionProfile": "coding",
-    "repository": "owner/repo",
-    "captureFolder": "codex",
     "rememberFolder": "codex-remember",
     "recallTimeframe": "7d",
-    "captureEvents": false,
+    "captureEvents": true,
     "redactKeys": [],
     "redactPaths": [],
-    "placementConventions": "Put decisions in decisions/ and work checkpoints in codex/."
+    "placementConventions": "Put decisions in decisions/ and work checkpoints in codex/<repo-dir>/."
   }
 }
 ```
 
-`captureEvents` is opt-in and off by default: only the JSON boolean `true`
-enables recording of redacted lifecycle-event envelopes to a local inbox under
-your Basic Memory home (`basic-memory hook status` / `basic-memory hook flush`).
-Add `redactKeys` and `redactPaths` arrays to extend the built-in redaction floor
-for repository-specific payload fields and paths.
+Codex event capture is on by default. Set the JSON boolean `false` at user or
+project level to opt out; malformed values fail closed. Captured, redacted
+lifecycle-event envelopes land in a local inbox under your Basic Memory home
+(`basic-memory hook status` / `basic-memory hook flush`). Add `redactKeys` and
+`redactPaths` arrays to extend the built-in redaction floor.
+
+When `captureFolder` is omitted, Codex resolves the Git top-level directory and
+writes to `codex/<repo-dir>`. An explicit folder still wins.
+
+For a coding profile, keep both the profile and checkout-specific repository
+identifier in the project file without duplicating the shared settings:
+
+```json
+{
+  "basicMemory": {
+    "sessionProfile": "coding",
+    "repository": "owner/repo"
+  }
+}
+```
 
 The plugin's seed schemas cover notes Codex writes directly: `codex_session`,
 `coding_session`, `decision`, and `task`. Coding sessions require structured

plugins/codex/hooks/pre_compact.py

@@ -2,7 +2,7 @@
 # /// script
 # requires-python = ">=3.12"
 # dependencies = [
-#     "basic-memory @ git+https://github.com/basicmachines-co/basic-memory@6e9f2fcf5f00f3577d38a3d8b6e2f2baca3079f7",
+#     "basic-memory @ git+https://github.com/basicmachines-co/basic-memory@bd5d145d5be3bab3c73291ae2a698f8e5a1e54cb",
 # ]
 # ///
 """PreCompact hook launcher backed by a pinned Basic Memory revision.

plugins/codex/hooks/session_start.py

@@ -2,7 +2,7 @@
 # /// script
 # requires-python = ">=3.12"
 # dependencies = [
-#     "basic-memory @ git+https://github.com/basicmachines-co/basic-memory@6e9f2fcf5f00f3577d38a3d8b6e2f2baca3079f7",
+#     "basic-memory @ git+https://github.com/basicmachines-co/basic-memory@bd5d145d5be3bab3c73291ae2a698f8e5a1e54cb",
 # ]
 # ///
 """SessionStart hook launcher backed by a pinned Basic Memory revision.

plugins/codex/skills/bm-checkpoint/SKILL.md

@@ -11,10 +11,11 @@ context transition.
 
 ## Gather
 
-Read `.codex/basic-memory.json` if present:
+Read `~/.codex/basic-memory.json`, then the nearest project
+`.codex/basic-memory.json`; project keys override user keys:
 
 - `primaryProject`, default omitted
-- `captureFolder`, default `codex`
+- `captureFolder`, default `codex/<git top-level directory name>`
 - `placementConventions`, optional
 - `sessionProfile`, default `general`
 - `repository`, required when `sessionProfile` is `coding`

plugins/codex/skills/bm-decide/SKILL.md

@@ -10,7 +10,8 @@ choice with rationale and consequences, not a casual preference.
 
 ## Steps
 
-1. Resolve `.codex/basic-memory.json`:
+1. Resolve `~/.codex/basic-memory.json`, then the nearest project
+   `.codex/basic-memory.json`; project keys override user keys:
    - write to `primaryProject` when set
    - follow `placementConventions` for the directory when they are specific
    - otherwise use `decisions`

plugins/codex/skills/bm-orient/SKILL.md

@@ -10,7 +10,8 @@ the user asks where things stand.
 
 ## Steps
 
-1. Read `.codex/basic-memory.json` if present. Use `primaryProject`, `secondaryProjects`,
+1. Read `~/.codex/basic-memory.json`, then the nearest project
+   `.codex/basic-memory.json`; project keys override user keys. Use `primaryProject`, `secondaryProjects`,
    `recallTimeframe`, `sessionProfile`, `repository`, and `placementConventions`.
    If the file is missing, continue
    against the default Basic Memory project and mention that setup has not been run.

plugins/codex/skills/bm-remember/SKILL.md

@@ -10,7 +10,8 @@ a small fact that should survive the current thread.
 
 ## Steps
 
-1. Read `.codex/basic-memory.json` if present:
+1. Read `~/.codex/basic-memory.json`, then the nearest project
+   `.codex/basic-memory.json`; project keys override user keys:
    - `primaryProject`, default omitted
    - `rememberFolder`, default `codex-remember`
 

plugins/codex/skills/bm-setup/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bm-setup
-description: Set up Basic Memory for Codex in the current repo by mapping a Basic Memory project, seeding schemas, and writing .codex/basic-memory.json.
+description: Set up Basic Memory for Codex at user or project level by mapping a Basic Memory project and seeding schemas.
 ---
 
 # Basic Memory for Codex Setup
@@ -25,6 +25,10 @@ Confirm Basic Memory is reachable before changing files:
 Ask the user to choose the project mapping. Do not infer write targets from the
 repo, default project, current directory, or previous local state.
 
+- config level: user-level `~/.codex/basic-memory.json` or project-level
+  `.codex/basic-memory.json`. Ask explicitly and recommend user level by default.
+  Project settings override user settings key by key, except `redactKeys` and
+  `redactPaths`, which accumulate so project config cannot weaken user privacy.
 - storage mode: cloud, local, or mixed. Prefer the user's stated mode over any
   CLI default.
 - `focus`: code/dev, research, writing, planning, or mixed.
@@ -35,13 +39,13 @@ repo, default project, current directory, or previous local state.
 - `primaryProject`: an existing Basic Memory project or a new one to create.
 - `secondaryProjects`: optional read-only projects for session-start context.
 - `teamProjects`: optional share targets for `bm-share`.
-- `captureFolder`: default `codex`.
+- `captureFolder`: default `codex/<repo-dir>`, derived from the Git top-level
+  directory. Ask only when the user wants an explicit override.
 - `rememberFolder`: default `codex-remember`.
 - `placementConventions`: a short note about where decisions, tasks, and research
   notes should land.
 - `captureEvents`: whether to record redacted lifecycle-event envelopes in the
-  local hook inbox. Default to `false`; SessionStart briefs and PreCompact
-  checkpoints work without it.
+  local hook inbox. Default to `true`; an explicit JSON boolean `false` opts out.
 - `redactKeys` and `redactPaths`: optional additions to the built-in redaction
   floor. Ask for these only when event capture is enabled or the user has
   repo-specific privacy requirements.
@@ -55,7 +59,8 @@ and optional pull-request metadata in Basic Memory.
 
 Explain the capture tradeoff before asking: enabled capture adds a local,
 redacted event trail that stays queued until `bm hook flush` projects it. It does
-not write to team projects, and only the JSON boolean `true` enables it.
+not write to team projects. The default is enabled; an explicit JSON boolean
+`false` disables it, and malformed values fail closed.
 
 If there are duplicate names, show qualified names and ask the user which one to
 use. Prefer qualified project names or project ids for cloud projects. Never pick
@@ -67,7 +72,8 @@ summarizing the real convention.
 
 ## Apply
 
-After confirming the plan, write `.codex/basic-memory.json` in the repo:
+After confirming the plan, write the shared settings to the chosen user-level or
+project-level file:
 
 ```json
 {
@@ -77,31 +83,48 @@ After confirming the plan, write `.codex/basic-memory.json` in the repo:
     "projectMode": "cloud",
     "teamProjects": {},
     "focus": "<focus>",
-    "sessionProfile": "coding",
-    "repository": "owner/name",
-    "captureFolder": "codex",
+    "sessionProfile": "<general-or-coding>",
     "rememberFolder": "codex-remember",
     "recallTimeframe": "7d",
-    "captureEvents": false,
+    "captureEvents": true,
     "redactKeys": [],
     "redactPaths": [],
     "placementConventions": "<short convention>"
   }
 }
 ```
 
-Preserve unrelated keys if the file already exists. Include `projectMode` when
-the user chose cloud, local, or mixed routing. Always persist `captureEvents` as
-a JSON boolean. Empty `redactKeys` and `redactPaths` lists may be omitted; when
-present, they must be JSON arrays of strings. `redactKeys` extends payload-key
-redaction, while `redactPaths` also protects working-directory and path-bearing
-checkpoint content. This file is intentionally Codex-specific; do not write
-`.claude/settings.json`.
-
-Persist `sessionProfile` explicitly. Persist `repository` only for the `coding`
-profile, after the user confirms it. A coding setup is incomplete without a
-repository identifier because the `coding_session` schema requires queryable Git
-identity fields.
+Omit `captureFolder` to use `codex/<repo-dir>`; persist it only for an explicit
+override. Preserve unrelated keys if the chosen file already exists. Include
+`projectMode` when the user chose cloud, local, or mixed routing. Always persist
+`captureEvents` as a JSON boolean. Empty `redactKeys` and `redactPaths` lists may
+be omitted; when present, they must be JSON arrays of strings. `redactKeys`
+extends payload-key redaction, while `redactPaths` also protects
+working-directory and path-bearing checkpoint content. User and project
+redaction lists accumulate. These files are intentionally Codex-specific; do
+not write `.claude/settings.json`.
+
+For a user-level coding setup, omit `sessionProfile` from the shared user file and
+keep both the coding profile and confirmed repository identifier in the project
+file so neither can affect other repositories:
+
+```json
+{
+  "basicMemory": {
+    "sessionProfile": "coding",
+    "repository": "owner/name"
+  }
+}
+```
+
+For a project-level setup, add `repository` to the shared settings in that same
+project file.
+
+Persist `sessionProfile` explicitly in the chosen file, except for a user-level
+coding setup where it belongs in the project file alongside `repository`. Persist
+`repository` only for the `coding` profile, after the user confirms it. A coding
+setup is incomplete without a repository identifier because the `coding_session`
+schema requires queryable Git identity fields.
 
 ## Seed Schemas
 

plugins/codex/skills/bm-share/SKILL.md

@@ -11,7 +11,8 @@ stay personal.
 
 ## Steps
 
-1. Read `.codex/basic-memory.json` and resolve:
+1. Read `~/.codex/basic-memory.json`, then the nearest project
+   `.codex/basic-memory.json`; project keys override user keys. Resolve:
    - `primaryProject`
    - `teamProjects`, a map of project ref to settings
 

plugins/codex/skills/bm-status/SKILL.md

@@ -19,8 +19,10 @@ Gather a concise diagnostic. Do not over-investigate.
    claiming the hooks cannot work.
 
 2. Plugin config:
-   - read `.codex/basic-memory.json`
-   - report `primaryProject`, `secondaryProjects`, `teamProjects`,
+   - read `~/.codex/basic-memory.json`, then the nearest project
+     `.codex/basic-memory.json`; project keys override user keys, while
+     `redactKeys` and `redactPaths` accumulate
+   - report the resolved `primaryProject`, `secondaryProjects`, `teamProjects`,
      `captureFolder`, `rememberFolder`, `recallTimeframe`, `focus`,
      `sessionProfile`, `repository`, `captureEvents`, `redactKeys`, and
      `redactPaths`

scripts/validate_codex_plugin.py

@@ -26,13 +26,17 @@
 REQUIRED_SKILL_TEXT: dict[str, tuple[str, ...]] = {
     "bm-setup": (
         "captureEvents",
+        "user-level",
+        "project-level",
+        "codex/<repo-dir>",
         "redactKeys",
         "redactPaths",
         "sessionProfile",
         "coding-session.md",
         "hook status --harness codex",
     ),
     "bm-status": (
+        "~/.codex/basic-memory.json",
         "hook status --harness codex",
         "pending envelopes",
         "processed envelopes",