mirror of
https://github.com/basicmachines-co/basic-memory
synced 2026-06-21 13:47:35 +00:00
Paul Hernandez
102 lines
3.7 KiB
Markdown
102 lines
3.7 KiB
Markdown
---
|
|
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.
|
|
---
|
|
|
|
# Basic Memory for Codex Setup
|
|
|
|
Set up the current repo so Codex can orient from Basic Memory and checkpoint work
|
|
back into it. Keep the interview short, but always ask before choosing where data
|
|
will be written.
|
|
|
|
## Preconditions
|
|
|
|
Confirm Basic Memory is reachable before changing files:
|
|
|
|
1. Prefer MCP: call `list_memory_projects`.
|
|
2. If MCP tools are not available, run `basic-memory --version` or `bm --version`.
|
|
3. If neither works, stop and tell the user to install Basic Memory and connect the
|
|
MCP server. The plugin bundles an `.mcp.json` that starts `uvx basic-memory mcp`.
|
|
4. List available projects before the interview. Include cloud/local source,
|
|
workspace, qualified name, and project id when available.
|
|
|
|
## Interview
|
|
|
|
Ask the user to choose the project mapping. Do not infer write targets from the
|
|
repo, default project, current directory, or previous local state.
|
|
|
|
- storage mode: cloud, local, or mixed. Prefer the user's stated mode over any
|
|
CLI default.
|
|
- `focus`: code/dev, research, writing, planning, or mixed.
|
|
- `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-sessions`.
|
|
- `rememberFolder`: default `codex-remember`.
|
|
- `placementConventions`: a short note about where decisions, tasks, and research
|
|
notes should land.
|
|
|
|
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
|
|
between cloud and local variants without confirmation.
|
|
|
|
For a new or empty project, suggest a light convention instead of creating empty
|
|
folders. For an existing project, inspect `list_directory` and a few notes before
|
|
summarizing the real convention.
|
|
|
|
## Apply
|
|
|
|
After confirming the plan, write `.codex/basic-memory.json` in the repo:
|
|
|
|
```json
|
|
{
|
|
"basicMemory": {
|
|
"primaryProject": "<project-ref>",
|
|
"secondaryProjects": [],
|
|
"projectMode": "cloud",
|
|
"teamProjects": {},
|
|
"focus": "<focus>",
|
|
"captureFolder": "codex-sessions",
|
|
"rememberFolder": "codex-remember",
|
|
"recallTimeframe": "7d",
|
|
"placementConventions": "<short convention>"
|
|
}
|
|
}
|
|
```
|
|
|
|
Preserve unrelated keys if the file already exists. Include `projectMode` when
|
|
the user chose cloud, local, or mixed routing. This file is intentionally
|
|
Codex-specific; do not write `.claude/settings.json`.
|
|
|
|
## Seed Schemas
|
|
|
|
Read the schema files from `<plugin-root>/schemas/`. This skill lives at
|
|
`<plugin-root>/skills/bm-setup/SKILL.md`, so the schemas are two directories up.
|
|
|
|
Seed these schema notes into the chosen `primaryProject` if they do not already
|
|
exist:
|
|
|
|
- `codex-session.md`
|
|
- `decision.md`
|
|
- `task.md`
|
|
|
|
Use `write_note` with `directory="schemas"`, `note_type="schema"`, schema
|
|
frontmatter as metadata, and the markdown body as content. Do not paste the YAML
|
|
frontmatter into content.
|
|
|
|
Before seeding schemas, restate the exact target project and ask for confirmation
|
|
if it differs from the user's selected primary project or if routing is
|
|
ambiguous.
|
|
|
|
## Verify
|
|
|
|
Before closing, prove the mapping works:
|
|
|
|
- Search the primary project for `type=schema` with page size 5.
|
|
- Search one shared project for open decisions if shared projects were configured.
|
|
- If either query errors, fix the project ref before finishing.
|
|
|
|
Finish with the project mapping, schemas seeded or skipped, and the verification
|
|
result. Tell the user that plugin hooks need to be reviewed and trusted in Codex
|
|
before they run.
|