---
title: bootstrap-memory
type: note
permalink: opencode-config/commands/bootstrap-memory
---

# Bootstrap Project Memory

RUN { git ls-files; git ls-files --others --exclude-standard; } 2>/dev/null | sort -u
READ README.md

You are bootstrapping basic-memory project notes for this project.

Your job is to inspect the codebase and create an initial knowledge baseline in
basic-memory. Capture architecture, core modules, conventions, and key decisions
so future sessions can resume quickly.

## Step 0: Ensure a dedicated per-repo basic-memory project exists

Use `list_memory_projects` to check whether this repo already has a basic-memory
project. If not, create one with `create_memory_project` using a short kebab-case
name (e.g., `my-web-app`) and the repo's root directory as `project_path`.

All subsequent `write_note`, `search_notes`, and `build_context` calls in this
command must pass `project="<repo-project-name>"` for project-specific notes, or
`project="main"` for cross-project reusable knowledge.

## Step 1: Check existing basic-memory state

Use `search_notes` and `build_context` (with `project="<repo-project-name>"`) to
check whether this project already has notes in basic-memory. Understanding
current state prevents duplication and helps you decide what to create vs update.

## Step 2: Inspect project structure

Run `git ls-files` to understand the project layout, then read `README.md` and
the highest-signal files for architecture and conventions.

Also check for existing cross-tool instruction files (`AGENTS.md`, `CLAUDE.md`,
`.cursorrules`, `.github/copilot-instructions.md`) — they may contain project
knowledge from other tools or team members that should be incorporated.

Identify:
- What the project does (primary capabilities)
- Core modules/subsystems and responsibilities
- Key patterns/conventions (naming, layering, testing, config)

## Step 3: Write initial knowledge notes

Use `write_note` (with `project="<repo-project-name>"`) to create project
knowledge notes under the `knowledge/` folder:
- Project purpose and scope
- Architecture overview
- Key modules with file paths
- Important implementation patterns/conventions

## Step 4: Seed decisions notes

Use `write_note` (with `project="<repo-project-name>"`) to create a `decisions/`
note with any clear, durable decisions found in docs or code patterns (for
example: stack choices, testing strategy, architectural constraints). Include
rationale when known.

## Step 5: Initialize plans/research notes

- If active in-progress work is discoverable, use `write_note` (with
  `project="<repo-project-name>"`) to create a `plans/<feature>` note with scope,
  tasks, and acceptance criteria.
- If research artifacts are discovered, use `write_note` (with
  `project="<repo-project-name>"`) to create a `research/<topic>` note with
  findings and references.

## Step 6: Record cross-project reusable knowledge

If you discover patterns, conventions, or tech knowledge that would benefit other
projects, use `write_note` with `project="main"` to record them as global notes.
Do not store project-specific plans, decisions, or session state in `main`.

## Step 7: Update instruction file

If `AGENTS.md` exists, update it with any new project knowledge discovered
during bootstrap (architecture, conventions, commands). Add the repo's
basic-memory project name (e.g., `opencode-config`) to `AGENTS.md` so
agents know which project to target. The symlinks (`CLAUDE.md`,
`.cursorrules`, `.github/copilot-instructions.md`) will automatically
reflect changes.

If the instruction file doesn't exist, note that `/init` should be run to create it.

## Guidelines

- Be specific with file paths, APIs, parameters, and behavioral details.
- Keep sections concise and scannable.
- Prefer durable knowledge over transient status notes.
- Use WikiLinks `[[Topic]]` to create relations between related notes.
- Use tags for categorization: `#pattern`, `#convention`, `#decision`, `#architecture`.
- Always pass the `project` parameter on every MCP call.