# Bm Orient

Resume from an exact Basic Memory checkpoint or orient Codex from current graph and...

- Repository: https://github.com/basicmachines-co/basic-memory (4440 stars)
- Category: Engineering
- License: AGPL-3.0
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add basicmachines-co/basic-memory --skill bm-orient -g -a claude-code -y`
Codex: `npx skills add basicmachines-co/basic-memory --skill bm-orient -g -a codex -y`
Cursor: `npx skills add basicmachines-co/basic-memory --skill bm-orient -g -a cursor -y`
Gemini CLI: `npx skills add basicmachines-co/basic-memory --skill bm-orient -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add basicmachines-co/basic-memory`

## Description

Resume from an exact Basic Memory checkpoint or orient Codex from current graph and repository evidence.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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. Accept an optional Basic Memory identifier,
permalink, or topic after `$bm-orient`.

When no project is pinned, discover projects with `bm_project(command="list")`
and pass the selected project's external ID as `project` on note/search calls.
With several addressable projects, these calls require an explicit scope even
when a default is configured.

## Resolve Configuration

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
by discovering projects and explicitly selecting the listed default or sole
project. Mention that setup has not been run.

## Choose One Recall Route

Choose exactly one route from the invocation.

### Exact checkpoint

When the user supplies an exact Basic Memory identifier or permalink, read that note directly.
When `primaryProject` is configured, call `bm_read` with both the exact
identifier and `project=<configured primaryProject>`. The explicit project is
required even when the identifier is a permalink, file path, or title. If setup
is missing, use a project-qualified pointer as its own route; otherwise discover
and explicitly select the listed default or sole project, and say that the
configured project scope could not be verified. Do not retry the identifier against secondary or other projects, search
for alternatives, or silently substitute a newer checkpoint. The exact pointer
and project are the user's chosen cursor.

### Topic discovery

When the user supplies a topic rather than an exact identifier, search the
primary project for matching `task`, `decision`, and `codex_session` notes.

The rest: https://github.com/basicmachines-co/basic-memory/blob/HEAD/plugins/codex/skills/bm-orient/SKILL.md