Basic Memory For Codex Status
Gather a concise diagnostic. Do not over-investigate.
Gather
CLI reachability:
basic-memory --version
- fallback
bm --version
- fallback
uvx --prerelease=allow basic-memory --version
Keep going if no launcher resolves. The plugin hook scripts can still use
their uv-managed environment; report hook health as unavailable instead of
claiming the hooks cannot work.
Plugin config:
- read
~/.codex/basic-memory.json, then the nearest project
.codex/basic-memory.json; project keys override user keys
- report the resolved
primaryProject, secondaryProjects, teamProjects,
captureFolder, rememberFolder, recallTimeframe, focus,
sessionProfile, repository, checkpointOnCompact, and captureEvents
- resolve omitted Codex defaults as
rememberFolder=codex/remember,
and checkpointOnCompact=true
Core hook health:
- with the first available launcher, run
basic-memory hook status --harness codex --project-dir <repo-root>
- report the shared inbox path, pending envelopes, archived envelopes, last
flush, settings state, resolved primary project, capture state, capture
folder, checkpoint-prompt state, Basic Memory version, and uv version from
that command
- inbox counts are global across supported harnesses; do not attribute a
backlog solely to Codex
- treat the command's settings resolution as canonical for hook behavior; if
it disagrees with the manually read config, show the mismatch
Hook files and launcher visibility:
- check
uv --version in the current environment independently of CLI
reachability; uv is a required hook prerequisite
- distinguish "uv missing from this shell" from "Desktop hook runtime
verified"; shell success does not establish the Desktop hook process's PATH
- when Desktop/WSL hooks fail while TUI works, inspect the actual hook
launch error and PATH;
uv: command not found occurs before the Python
script can emit a diagnostic
- consult
../../README.md under "Troubleshooting Desktop hooks on WSL"
for the default-location probe and conditional symlink workaround
- only report Desktop hook execution as verified when startup context and a
post-compaction checkpoint note were observed; otherwise label it unverified
- confirm
plugins/codex/hooks/hooks.json exists if running from this repo
- remind the user that Codex plugin hooks must be reviewed and trusted before
they run
Basic Memory queries:
- query recent
type=codex_session; when
sessionProfile=coding, also query type=coding_session with
repository=<configured repository>, then merge, deduplicate, sort newest
first, and keep the newest five; never run an unscoped coding-session query
when the repository is missing; these are agent-authored checkpoints, while
lifecycle envelopes remain local operational trace
- active
type=task, status=active
- open
type=decision, status=open
Present
Use this shape:
Basic Memory for Codex
- CLI: <version or missing>
- Project: <primaryProject or default>
- Reads from: <secondaryProjects or none>
- Share targets: <teamProjects or none>
- Capture folder: <captureFolder>
- Remember folder: <rememberFolder>
- Recall timeframe: <recallTimeframe>
- Session profile: <general | coding>
- Repository: <owner/name or none>
- Checkpoint on compact: <enabled | disabled>
- Event capture: <enabled | disabled>
- Shared hook inbox: <path or unavailable>
- Shared pending envelopes: <count or unavailable>
- Shared archived envelopes: <count or unavailable>
- Last flush: <timestamp, never, or unavailable>
- Hook runtime in this environment: basic-memory <version>; uv <version or missing>
- Desktop hook execution: <verified from context and checkpoint | unverified>
- Recent checkpoints: <count across coding_session and codex_session>
- Active tasks: <count>
- Open decisions: <count>
- Hooks: installed; trust review required in Codex
List recent checkpoints by type, title, and permalink when available. Warn when
event capture is enabled and pending envelopes are accumulating or the last flush
is never, while noting that another harness may contribute to the shared counts.
Do not warn about an empty inbox when capture is disabled.
1---
2name: bm-status
3description: Report the Basic Memory for Codex configuration, reachability, hook expectations, recent Codex checkpoints, and active tasks.
4metadata:
5 source: https://skillmd.com/skills/basicmachines-co-basic-memory/bm-status
6---
7
8# Basic Memory For Codex Status
9
10Gather a concise diagnostic. Do not over-investigate.
11
12## Gather
13
141. CLI reachability:
15 - `basic-memory --version`
16 - fallback `bm --version`
17 - fallback `uvx --prerelease=allow basic-memory --version`
18
19 Keep going if no launcher resolves. The plugin hook scripts can still use
20 their uv-managed environment; report hook health as unavailable instead of
21 claiming the hooks cannot work.
22
232. Plugin config:
24 - read `~/.codex/basic-memory.json`, then the nearest project
25 `.codex/basic-memory.json`; project keys override user keys
26 - report the resolved `primaryProject`, `secondaryProjects`, `teamProjects`,
27 `captureFolder`, `rememberFolder`, `recallTimeframe`, `focus`,
28 `sessionProfile`, `repository`, `checkpointOnCompact`, and `captureEvents`
29 - resolve omitted Codex defaults as `rememberFolder=codex/remember`,
30 and `checkpointOnCompact=true`
31
323. Core hook health:
33 - with the first available launcher, run
34 `basic-memory hook status --harness codex --project-dir <repo-root>`
35 - report the shared inbox path, pending envelopes, archived envelopes, last
36 flush, settings state, resolved primary project, capture state, capture
37 folder, checkpoint-prompt state, Basic Memory version, and uv version from
38 that command
39 - inbox counts are global across supported harnesses; do not attribute a
40 backlog solely to Codex
41 - treat the command's settings resolution as canonical for hook behavior; if
42 it disagrees with the manually read config, show the mismatch
43
444. Hook files and launcher visibility:
45 - check `uv --version` in the current environment independently of CLI
46 reachability; uv is a required hook prerequisite
47 - distinguish "uv missing from this shell" from "Desktop hook runtime
48 verified"; shell success does not establish the Desktop hook process's PATH
49 - when Desktop/WSL hooks fail while TUI works, inspect the actual hook
50 launch error and PATH; `uv: command not found` occurs before the Python
51 script can emit a diagnostic
52 - consult `../../README.md` under "Troubleshooting Desktop hooks on WSL"
53 for the default-location probe and conditional symlink workaround
54 - only report Desktop hook execution as verified when startup context and a
55 post-compaction checkpoint note were observed; otherwise label it unverified
56 - confirm `plugins/codex/hooks/hooks.json` exists if running from this repo
57 - remind the user that Codex plugin hooks must be reviewed and trusted before
58 they run
59
605. Basic Memory queries:
61 - query recent `type=codex_session`; when
62 `sessionProfile=coding`, also query `type=coding_session` with
63 `repository=<configured repository>`, then merge, deduplicate, sort newest
64 first, and keep the newest five; never run an unscoped coding-session query
65 when the repository is missing; these are agent-authored checkpoints, while
66 lifecycle envelopes remain local operational trace
67 - active `type=task`, `status=active`
68 - open `type=decision`, `status=open`
69
70## Present
71
72Use this shape:
73
74```text
75Basic Memory for Codex
76- CLI: <version or missing>
77- Project: <primaryProject or default>
78- Reads from: <secondaryProjects or none>
79- Share targets: <teamProjects or none>
80- Capture folder: <captureFolder>
81- Remember folder: <rememberFolder>
82- Recall timeframe: <recallTimeframe>
83- Session profile: <general | coding>
84- Repository: <owner/name or none>
85- Checkpoint on compact: <enabled | disabled>
86- Event capture: <enabled | disabled>
87- Shared hook inbox: <path or unavailable>
88- Shared pending envelopes: <count or unavailable>
89- Shared archived envelopes: <count or unavailable>
90- Last flush: <timestamp, never, or unavailable>
91- Hook runtime in this environment: basic-memory <version>; uv <version or missing>
92- Desktop hook execution: <verified from context and checkpoint | unverified>
93- Recent checkpoints: <count across coding_session and codex_session>
94- Active tasks: <count>
95- Open decisions: <count>
96- Hooks: installed; trust review required in Codex
97```
98
99List recent checkpoints by type, title, and permalink when available. Warn when
100event capture is enabled and pending envelopes are accumulating or the last flush
101is `never`, while noting that another harness may contribute to the shared counts.
102Do not warn about an empty inbox when capture is disabled.