| name | bm-orient |
| description | Orient Claude from Basic Memory before substantial repo work by reading active tasks, open decisions, recent checkpoints, and repo conventions. Use when resuming old work or when the user asks where things stand. |
| argument-hint | (no arguments — reads the graph and summarizes) |
Orient From Basic Memory
Use this before substantial work in a repo, before resuming an old thread, or when
the user asks where things stand. The SessionStart hook already briefs the start
of a session; this is the deliberate mid-session version with deeper reads.
Steps
-
Resolve config: read the basicMemory block with the same precedence the
hooks use. For the user-level base, append settings.json to the literal value
of CLAUDE_CONFIG_DIR when that environment variable is present; do not trim
it, expand ~, or treat an empty value as unset. Use ~/.claude/settings.json
only when the variable is absent. Then the project's .claude/settings.json
and .claude/settings.local.json override it per key. Use primaryProject,
secondaryProjects, recallTimeframe, sessionProfile, repository, and
placementConventions. If no config is present, continue against the default
Basic Memory project and mention that setup has not been run. Scope queries to
primaryProject by passing it as project, or as project_id if it's an
external_id UUID.
-
Query the primary project with search_notes:
- active tasks:
metadata_filters={"type": "task", "status": "active"}
- open decisions:
metadata_filters={"type": "decision", "status": "open"}
- recent sessions:
metadata_filters={"type": "session"}, after
recallTimeframe
- recent coding sessions:
metadata_filters={"type": "coding_session", "repository": "<configured repository>"}, after recallTimeframe, when
sessionProfile is coding
Always query "type": "session"; include "type": "coding_session" for a
coding profile only with the configured repository metadata filter.
Never run an unscoped coding-session query; if the repository is missing,
report that setup is incomplete. Merge and deduplicate the results, sort them
newest first, and prefer the highest-signal checkpoint regardless of which
producer wrote it. coding_session carries schema-required, queryable Git
context; session covers general checkpoints and PreCompact captures. Do not
query lifecycle trace: bm hook flush archives it locally rather than
promoting it into the graph.
-
Query configured secondaryProjects read-only for open decisions. Do not write
to shared projects during orientation.
-
Read the highest-signal hits before summarizing. Prefer notes that match the
current repository, branch, Git SHA, pull request, named route, issue, or file
path. For coding sessions, use structured metadata filters before text search.
-
Present a compact orientation:
- active work
- decisions that constrain the next move
- recent checkpoint cursor
- likely next action
- any missing setup or ambiguous project mapping
Keep the summary evidence-backed. Include permalinks for notes you rely on.
