@basicmemory/openclaw-basic-memory 0.24.0 → 1.0.0

package/skills/memory-literary-analysis/SKILL.md

@@ -7,6 +7,17 @@ description: "Analyze a complete literary work into a structured Basic Memory kn
 
 Transform a complete literary work into a structured knowledge graph. Characters, themes, chapters, locations, symbols, and literary devices become interconnected notes — searchable, validatable, and traversable.
 
+## Project scope
+
+If the project is unknown, discover it with `bm_project(command="list")`.
+Pass a nonempty `project` on every note, folder, context and schema call, even
+with one project or a qualified `memory://` URL. Use the chosen project's name,
+`workspace/project`, or external ID; `<work-name>` below is a placeholder for it.
+Recent activity also requires `project`. Search accepts `project` for one
+project, `projects` for selected projects, or `all_projects=True` explicitly.
+Discovery and bundled manuals need no project. Keep the same scope when following
+returned paths, paginating, or recovering from a refusal.
+
 ## When to Use
 
 - Analyzing a novel, play, poem, or non-fiction book end-to-end
@@ -28,10 +39,9 @@ Phase 5: Explore       → traverse the graph, write synthesis notes
 
 ## Tools
 
-Writing always goes through `write_note` and `edit_note`. For *reading* — which is most of
-the work in a long analysis — prefer the POSIX read verbs where they are available
-(the MCP `cat`, `find`, `grep`, and `ls` tools are on by default; the `bm` CLI verbs are always
-available):
+Writing goes through `bm_write` and `bm_edit`. MCP reads use `bm_read`, `bm_find`,
+`bm_search`, and `bm_list`. The CLI keeps its POSIX verbs; the table and shell
+examples below are CLI commands (prefix each verb with `bm`):
 
 | Need | Use | Instead of |
 |------|-----|-----------|
@@ -55,7 +65,7 @@ answer, exit 0, no warning — so learn it here rather than from a graph you tho
 audited:
 
 - **`find` pages, and the default page is 10.** Any query whose answer is "all N chapters"
-  needs `--page-size 200` (the maximum) — see [Coverage Checks](#coverage-checks).
+  needs `--page-size 100` (the maximum) and paging — see [Coverage Checks](#coverage-checks).
 - **`--name` cannot combine with `--meta`.** The metadata search has no filename glob. Scope a
   `--meta` query with the positional path instead: `find /characters --meta
   'note_type=character'`. That path is matched on a directory boundary against the *file path*
@@ -64,15 +74,19 @@ audited:
   `/characters` reaches everything filed under `characters/` (including `characters/major/`),
   and never `characters-cut/`.
 
-If the POSIX verbs are unavailable, every step below still works with `search_notes`,
-`read_note`, and `list_directory` — it just costs more.
+For MCP, use `bm_read(identifier="<note>", section="Observations", project="<work-name>")` or
+`start_line`/`end_line` for slices. Use `bm_find(filters={"type": "chapter"}, fields=["chapter_number", "pov"], project="<work-name>")`
+for metadata and `bm_search(query="doubloon", lines=2, project="<work-name>")`
+for matching lines. `bm_list` lists one folder level; `bm_find` recurses.
+MCP list/find/search pages cap at 100; follow `has_more` through every page.
+CLI page sizes and flags below are separate from the MCP shapes.
 
 ## Phase 0: Setup
 
 ### Create the Project
 
 ```python
-create_memory_project(project_name="<work-name>", project_path="~/basic-memory/<work-name>")
+bm_project(command="create", name="<work-name>", path="~/basic-memory/<work-name>")
 ```
 
 Use a kebab-case slug of the work's title (e.g., `great-gatsby`, `hamlet`, `beloved`).
@@ -84,7 +98,7 @@ Write 6 schema notes to `schema/`. Each schema defines the entity type's fields,
 #### Character Schema
 
 ```python
-write_note(
+bm_write(
   title="Character",
   directory="schema",
   note_type="schema",
@@ -106,7 +120,8 @@ Schema for character entity notes.
 ## Observations
 - [convention] Major characters in characters/major/, minor in characters/minor/
 - [convention] Observation categories: trait, motivation, arc, quote, appearance, relationship, symbolism, fate
-- [convention] Relations: appears_in, contrasts_with, allied_with, commands, symbolizes, associated_with"""
+- [convention] Relations: appears_in, contrasts_with, allied_with, commands, symbolizes, associated_with""",
+  project="<work-name>",
 )
 ```
 
@@ -115,7 +130,7 @@ Add work-specific fields as needed — e.g., `rank` for military fiction, `house
 #### Theme Schema
 
 ```python
-write_note(
+bm_write(
   title="Theme",
   directory="schema",
   note_type="schema",
@@ -135,14 +150,15 @@ Schema for thematic analysis notes.
 
 ## Observations
 - [convention] Observation categories: definition, manifestation, evolution, counterpoint, quote, interpretation
-- [convention] Relations: embodied_by, contrasts_with, reinforced_by, explored_in, expressed_through"""
+- [convention] Relations: embodied_by, contrasts_with, reinforced_by, explored_in, expressed_through""",
+  project="<work-name>",
 )
 ```
 
 #### Chapter Schema
 
 ```python
-write_note(
+bm_write(
   title="Chapter",
   directory="schema",
   note_type="schema",
@@ -164,14 +180,15 @@ Schema for chapter-level analysis notes.
 ## Observations
 - [convention] Chapters stored in chapters/ directory
 - [convention] Observation categories: summary, event, tone, technique, quote, significance, foreshadowing
-- [convention] Relations: features, set_in, explores, contains, employs, follows, precedes, parallels"""
+- [convention] Relations: features, set_in, explores, contains, employs, follows, precedes, parallels""",
+  project="<work-name>",
 )
 ```
 
 #### Location Schema
 
 ```python
-write_note(
+bm_write(
   title="Location",
   directory="schema",
   note_type="schema",
@@ -191,14 +208,15 @@ Schema for location and setting notes.
 
 ## Observations
 - [convention] Observation categories: description, atmosphere, symbolism, significance, geography
-- [convention] Relations: setting_for, associated_with, symbolizes, contains, part_of"""
+- [convention] Relations: setting_for, associated_with, symbolizes, contains, part_of""",
+  project="<work-name>",
 )
 ```
 
 #### Symbol Schema
 
 ```python
-write_note(
+bm_write(
   title="Symbol",
   directory="schema",
   note_type="schema",
@@ -218,14 +236,15 @@ Schema for symbolic element notes.
 
 ## Observations
 - [convention] Observation categories: meaning, appearance, ambiguity, interpretation, quote, evolution
-- [convention] Relations: represents, associated_with, appears_in, contrasts_with, located_at"""
+- [convention] Relations: represents, associated_with, appears_in, contrasts_with, located_at""",
+  project="<work-name>",
 )
 ```
 
 #### LiteraryDevice Schema
 
 ```python
-write_note(
+bm_write(
   title="LiteraryDevice",
   directory="schema",
   note_type="schema",
@@ -245,7 +264,8 @@ Schema for literary technique and device notes.
 
 ## Observations
 - [convention] Observation categories: definition, usage, effect, example, significance
-- [convention] Relations: used_in, characterizes, expresses, related_to"""
+- [convention] Relations: used_in, characterizes, expresses, related_to""",
+  project="<work-name>",
 )
 ```
 
@@ -276,7 +296,7 @@ Before processing chapters, create stub notes for major entities so `[[wiki-link
 For each major character, create a stub with known metadata:
 
 ```python
-write_note(
+bm_write(
   title="<Character Name>",
   directory="characters/major",
   note_type="Character",
@@ -290,7 +310,8 @@ write_note(
 
 ## Relations
 - associated_with [[<Related Character>]]
-- appears_in [[<Key Location>]]"""
+- appears_in [[<Key Location>]]""",
+  project="<work-name>",
 )
 ```
 
@@ -340,14 +361,14 @@ re-reading the whole book into context:
 
 ```bash
 grep -n '^CHAPTER ' ~/basic-memory/moby-dick/moby-dick.txt   # heading -> line number
-bm cat moby-dick/moby-dick.txt --lines 4200-4890 --plain   # one chapter, not the whole text
+bm cat moby-dick.txt --lines 4200-4890 --project moby-dick   # one chapter, not the whole text
 ```
 
 `grep -n` here is the shell's grep on a filesystem path (this is the map-building step, and
-it needs the file). `bm cat` then takes the *note identifier* and returns exactly that slice plus a
-`lines 4200-4890 of N` footer. Spell the identifier project-qualified
-(`<work>/<work>.txt`) so it routes to the right project. `bm head moby-dick/moby-dick.txt -n 40` is the cheap
-way to eyeball the heading format before writing the grep pattern.
+it needs the file). `bm cat` then takes the *note identifier* and returns exactly that slice,
+numbered, under a `Lines 4200-4890 of N` header. Pass `--project <work>` so it reads from the
+right project. `bm head moby-dick.txt -n 40 --project moby-dick` is the cheap way to eyeball
+the heading format before writing the grep pattern.
 
 Store the map in the project (a note or a small JSON file) so later batches — and a resumed
 run after context compaction — do not have to rediscover it. On a long work this is the
@@ -378,7 +399,7 @@ never work from memory or a summary; textual evidence is the entire point.
 **2. Create the chapter note:**
 
 ```python
-write_note(
+bm_write(
   title="Chapter <N> - <Title>",
   directory="chapters",
   note_type="Chapter",
@@ -407,19 +428,21 @@ write_note(
 - contains [[<Symbol>]]
 - employs [[<Literary Device>]]
 - follows [[Chapter <N-1> - <Previous Title>]]
-- precedes [[Chapter <N+1> - <Next Title>]]"""
+- precedes [[Chapter <N+1> - <Next Title>]]""",
+  project="<work-name>",
 )
 ```
 
 **3. Enrich related entities:**
 
 ```python
-edit_note(
+bm_edit(
   identifier="characters/major/<character-slug>",
-  operation="insert_after_section",
+  command="insert_after_section",
   section="Observations",
   content="""- [arc] Ch.<N>: <What happens to this character>
-- [quote] "<Attributed quote>" (Ch.<N>)"""
+- [quote] "<Attributed quote>" (Ch.<N>)""",
+  project="<work-name>",
 )
 ```
 
@@ -452,7 +475,7 @@ As each chapter is processed, append observations to relevant entities:
 
 ### Adding Prose and Interpretation
 
-After the structured observations are in place, consider adding interpretive prose to major entity notes. Insert 2-4 paragraphs of critical essay before the Observations section with `edit_note(operation="insert_before_section", section="Observations", content=...)`. This prose should:
+After the structured observations are in place, consider adding interpretive prose to major entity notes. Insert 2-4 paragraphs of critical essay before the Observations section with `bm_edit(command="insert_before_section", section="Observations", content=..., project="<work-name>")`. This prose should:
 
 - Argue for a reading of the character, theme, or symbol — not just describe it
 - Connect the entity to the work's larger concerns and to literary tradition
@@ -470,17 +493,17 @@ After all chapters are processed:
 Do not re-read every note to decide what is thin. Query for it:
 
 ```bash
-bm find --meta 'note_type=chapter' --fields chapter_number,pov,setting --page-size 200
-bm find --meta 'note_type=character' --fields role,status --page-size 200   # who is still a stub
-bm find --meta 'chapter_number>100' --fields pov --page-size 200           # late-book POV drift
+bm find --meta 'note_type=chapter' --fields chapter_number,pov,setting --page-size 100
+bm find --meta 'note_type=character' --fields role,status --page-size 100   # who is still a stub
+bm find --meta 'chapter_number>100' --fields pov --page-size 100           # late-book POV drift
 ```
 
-A field a note never set comes back as a blank cell (`null` under `--json`), so rows with
+A field a note never set comes back as `None` (`null` under `--json`), so rows with
 blanks are the work queue. This turns "audit the graph" from a read of every note into one
 call per question.
 
-`write_note` snake-cases `note_type` (`Chapter` is stored as `chapter`), and `--meta`
-type predicates are normalized the same way, so either spelling matches. `--page-size 200`
+`bm_write` snake-cases `note_type` (`Chapter` is stored as `chapter`), and `--meta`
+type predicates are normalized the same way, so either spelling matches. `--page-size 100`
 is not decoration: without it these return the first 10 rows and the work queue looks ten
 items long.
 
@@ -497,7 +520,7 @@ Add `parallels` and `contrasts_with` relations between structurally similar chap
 Create synthesis notes in `analysis/`:
 
 ```python
-write_note(
+bm_write(
   title="Narrative Structure",
   directory="analysis",
   note_type="note",
@@ -515,7 +538,8 @@ Analysis of the work's narrative architecture.
 - analyzes [[<Protagonist>]]
 - analyzes [[<Key Character>]]
 - explores [[<Central Theme>]]
-..."""
+...""",
+  project="<work-name>",
 )
 ```
 
@@ -533,23 +557,23 @@ During chapter processing, new minor characters, locations, and symbols will eme
 
 ```python
 # Validate each entity type
-schema_validate(note_type="Character")
-schema_validate(note_type="Theme")
-schema_validate(note_type="Chapter")
-schema_validate(note_type="Location")
-schema_validate(note_type="Symbol")
-schema_validate(note_type="LiteraryDevice")
+bm_schema(command="validate", note_type="Character", project="<work-name>")
+bm_schema(command="validate", note_type="Theme", project="<work-name>")
+bm_schema(command="validate", note_type="Chapter", project="<work-name>")
+bm_schema(command="validate", note_type="Location", project="<work-name>")
+bm_schema(command="validate", note_type="Symbol", project="<work-name>")
+bm_schema(command="validate", note_type="LiteraryDevice", project="<work-name>")
 ```
 
 ### Drift Detection
 
 ```python
-schema_diff(note_type="Character")
+bm_schema(command="diff", note_type="Character", project="<work-name>")
 # ... for each type
 ```
 
 Fix issues found — common fixes:
-- Missing required observation categories → add them via `edit_note`
+- Missing required observation categories → add them via `bm_edit`
 - Enum values outside allowed set → correct metadata
 - Fields in notes but not schema → add as optional to schema if legitimate
 
@@ -558,14 +582,14 @@ Fix issues found — common fixes:
 Schema validation proves notes match their shape. These prove the graph is *complete*:
 
 ```bash
-bm find --meta 'note_type=chapter' --fields chapter_number --page-size 200   # every chapter present?
-bm find --meta 'note_type=chapter' --fields pov,setting --page-size 200      # missing context?
-bm find /characters --meta 'note_type=character' --fields role --page-size 200  # inventory vs. seed list
+bm find --meta 'note_type=chapter' --fields chapter_number --page-size 100   # every chapter present?
+bm find --meta 'note_type=chapter' --fields pov,setting --page-size 100      # missing context?
+bm find /characters --meta 'note_type=character' --fields role --page-size 100  # inventory vs. seed list
 ```
 
 **A coverage check that pages is not a coverage check.** `bm find` defaults to
 `--page-size 10`, so the un-sized form of the first query "proves" a 138-chapter work has 10
-chapters. 200 is the maximum page size; past that, iterate with `--page 2`, `--page 3`, … .
+chapters. 100 is the maximum page size; past that, iterate with `--page 2`, `--page 3`, … .
 Scope a `--meta` query with the positional path (`/characters`), never `--name` — the two
 options are mutually exclusive, because the metadata search has no filename glob. The
 positional path scopes by the *file path* a note is indexed under, matched on a directory
@@ -573,12 +597,10 @@ boundary: `/characters` admits `characters/major/ahab.md` but never `characters-
 not a permalink match, so a note that pins its own `permalink:` is still found where its file
 lives.
 
-Read the count off the footer, not off the rows you can see. In a terminal every `find`
-result reports `page 1 • total 138`, and appends `• more available (--page)` when the page
-truncated the answer — that suffix appearing is the check *failing*, whatever the visible
-rows say. **The footer is a TTY feature.** Piped output without `--plain` is JSON, which
-carries `total` and `has_more`; with `--plain` the rows go to stdout and a has-more notice
-goes to stderr. For scripts, read `has_more` from `--json`.
+Read the count off the result, not off the rows you can see. The text result opens with the
+total (`138 notes under '/' match:`) and ends with `More results available.` when the page
+truncated the answer — that line appearing is the check *failing*, whatever the visible rows
+say. For scripts, read `total` and `has_more` from `--json`.
 
 For the sequence gap — the failure that a count alone cannot catch — take the numbers from
 `--json`, which carries `total`, `total_is_exact`, and `has_more`:
@@ -587,7 +609,7 @@ For the sequence gap — the failure that a count alone cannot catch — take th
 expected=138; page=1; rows='[]'
 while :; do
   resp=$(bm find --meta 'note_type=chapter' --fields chapter_number \
-           --page-size 200 --page $page --project <work> --json)
+           --page-size 100 --page $page --project <work> --json)
   rows=$(jq -n --argjson acc "$rows" --argjson r "$resp" \
            '$acc + [$r.results[] | {title, n: .fields.chapter_number}]')
   [ "$(jq -r '.has_more' <<<"$resp")" = "true" ] || break
@@ -603,9 +625,9 @@ jq -n --argjson rows "$rows" --argjson expected "$expected" '
       out_of_range: ($n | map(select(. < 1 or . > $expected)) | unique) }'
 ```
 
-The loop is not ceremony. `--page-size` caps at 200, so a single call cannot inventory a work
-with more than 200 chapters — and rerunning it with `--page 2` *replaces* the numbers rather
-than accumulating them, which reports chapters 1-200 as missing on a corpus that is complete.
+The loop is not ceremony. `--page-size` caps at 100, so a single call cannot inventory a work
+with more than 100 chapters — and rerunning it with `--page 2` *replaces* the numbers rather
+than accumulating them, which reports chapters 1-100 as missing on a corpus that is complete.
 Walk until `has_more` is false and check the union.
 
 `--fields` returns YAML-native types, so `chapter_number: 63` comes back as `63`. The
@@ -643,7 +665,7 @@ bm orphans          # entities with no relations in the graph
 ```
 
 `orphans` finds notes with no relations. It does not find a `[[target]]` that resolves to
-nothing — a misspelled or renamed entity name. Check a chapter's links with `bm tool build-context memory://chapters/<slug> --depth 1
+nothing — a misspelled or renamed entity name. Check a chapter's links with `bm tool context memory://chapters/<slug> --depth 1
 --project <work> --json` and look for relations whose `to_entity_id` is `null`; fix the
 spelling or add the alias, then re-run the chapter.
 
@@ -655,18 +677,32 @@ orphans behind has made the graph worse.
 With the graph complete, traverse it to find what the chapter-by-chapter pass could not see:
 
 ```bash
-bm grep "features [[" --page-size 200 --project <work> --json   # every chapter's cast, one call
-bm find --meta 'note_type=theme' --fields prevalence --page-size 200  # thematic weight
+bm find --meta 'note_type=theme' --fields prevalence --page-size 100  # thematic weight
 bm grep "doubloon" --page-size 100 --project <work>                # every mention of a symbol
 ```
 
-"Which characters share the most chapters" is the first line plus a local parse of each
-row's `content` for `features [[...]]` — one call instead of a read per chapter. Do not
-reach for `bm tool build-context 'memory://characters/major/*'` here: a
+"Which characters share the most chapters" is a search for `features [[` plus a local parse
+of each row's `content` for `features [[...]]` — one call per 100 chapters instead of a read
+per chapter. Page until `has_more` is false, as the coverage check does; a 138-chapter work
+needs two pages:
+
+```bash
+page=1; rows='[]'
+while :; do
+  resp=$(bm grep "features [[" --page-size 100 --page $page --project <work> --json)
+  rows=$(jq -n --argjson acc "$rows" --argjson r "$resp" '$acc + $r.results')
+  [ "$(jq -r '.has_more' <<<"$resp")" = "true" ] || break
+  page=$((page + 1))
+done
+jq 'length' <<<"$rows"   # one row per chapter that lists its cast
+```
+
+Do not
+reach for `bm tool context 'memory://characters/major/*'` here: a
 wildcard context is capped at 100 related rows across all primaries and returns one primary
 row per indexed observation, so it neither enumerates the cast nor walks the web.
-`build-context` on a *single* note is the right tool for a different question, below.
-`build-context` takes its URL as a positional argument — there is no `--url` option.
+`context` on a *single* note is the right tool for a different question, below.
+`context` takes its URL as a positional argument — there is no `--url` option.
 
 `grep` matches keywords and returns a page of 10, which quietly truncates "where does this
 appear?" — a symbol in 40 chapters comes back as 10. For symbol tracing, raise
@@ -675,14 +711,15 @@ the default page would have dropped. `--semantic` ranks by meaning instead, whic
 "what is this about?" rather than "where does this word appear?".
 
 Two more facts about `grep` rows. Matching is case-insensitive and note-level: a hit is a
-note, not a line, and there is no `-n` or context. And each row's `content` is capped at
+note, not a line, unless you pass `-C N` for matching lines with context. And each row's
+`content` is capped at
 4000 characters; `content_truncated: true` marks a cut row, so a long note's tail (such as a
 final chapter's `follows`/`precedes` relations) may be missing from a grep-driven scan.
 When a parse depends on the end of a note, `cat` that note.
 
 `--page-size` raises the ceiling, it does not remove it. A symbol in a long work can exceed
-even 100, so check whether the last page was full and walk `--page 2`, `--page 3` until it is
-not. A truncated symbol search fails the same silent way as an unpaginated `find`: a plausible
+even 100, so walk `--page 2`, `--page 3` until `has_more` is false, as in the cast loop
+above. A truncated symbol search fails the same silent way as an unpaginated `find`: a plausible
 answer, exit 0, and no sign that the tail is missing.
 
 And `grep` searches **your notes, not the source**. The `<work>.txt` is indexed as an entity,
@@ -738,7 +775,7 @@ This pipeline works for any literary text. Adjust schemas for genre:
 - **Relations are your web.** Every chapter should link to characters, themes, locations, and devices. Every entity should link back to chapters where it appears.
 - **Enrich iteratively.** Entity notes grow richer with each chapter. Don't try to write the perfect character note upfront — append as you go.
 - **Add prose for depth.** After structured data is in place, add interpretive essays to major notes. The prose captures what observations cannot: argument, nuance, opinion, and voice.
-- **Validate periodically.** Run `schema_validate` after each batch, not just at the end. Catch drift early.
+- **Validate periodically.** Run `bm_schema(command="validate", project="<work-name>")` after each batch, not just at the end. Catch drift early.
 - **Quote generously.** Literary analysis lives on textual evidence. Include significant quotes as `[quote]` observations with chapter attribution.
 - **Review and revise.** After completing all chapters, review the full graph from an external perspective. Look for thin notes, missing connections, and gaps in coverage. The first pass is never the last.
 - **Analysis comes last.** Synthesis notes in `analysis/` should be written after all chapters are processed, when you have the full picture.

package/skills/memory-metadata-search/SKILL.md

@@ -7,6 +7,17 @@ description: "Search Basic Memory notes by custom frontmatter fields with equali
 
 Find notes by their structured frontmatter fields instead of (or in addition to) free-text content. Any custom YAML key in a note's frontmatter beyond the standard set (`title`, `type`, `tags`, `permalink`, `schema`) is automatically indexed as `entity_metadata` and becomes queryable.
 
+## Project scope
+
+If the project is unknown, discover it with `bm_project(command="list")`.
+Pass a nonempty `project` on every note, folder, context and schema call, even
+with one project or a qualified `memory://` URL. Use the chosen project's name,
+`workspace/project`, or external ID; `<project>` below is a placeholder for it.
+Recent activity also requires `project`. Search accepts `project` for one
+project, `projects` for selected projects, or `all_projects=True` explicitly.
+Discovery and bundled manuals need no project. Keep the same scope when following
+returned paths, paginating, or recovering from a refusal.
+
 ## When to Use
 
 - **Filtering by status or priority** — find all notes with `status: draft` or `priority: high`
@@ -18,7 +29,7 @@ Find notes by their structured frontmatter fields instead of (or in addition to)
 
 ## The Tool
 
-All metadata searching uses `search_notes`. Pass filters via `metadata_filters`, or use the `tags` and `status` convenience shortcuts. Omit `query` (or pass `None`) for filter-only searches.
+Use `bm_search` for ranked results or `bm_find` for file discovery with selected fields. Pass frontmatter conditions via `filters`, including tags and status. Omit `query` (or pass `None`) for filter-only searches.
 
 ## Filter Syntax
 
@@ -104,43 +115,43 @@ against the value and a comparison with null is never true.
 
 Frontmatter fields say when a note was filed or reviewed. To ask what a note
 *claims was true* on a date, use observation qualifiers (see **memory-notes**)
-and `search_notes(valid_at="2026-07-01")` or
-`search_notes(valid_overlaps="[2026-07-01,2026-08-01)")`.
+and `bm_search(valid_at="2026-07-01", project="<project>")` or
+`bm_search(valid_overlaps="[2026-07-01,2026-08-01)", project="<project>")`.
 
-## Using `search_notes` with Metadata
+## Using `bm_search` with Metadata
 
-Pass `metadata_filters`, `tags`, or `status` to `search_notes`. Omit `query` for filter-only searches, or combine text and filters together.
+Pass `filters` to `bm_search`. Omit `query` for filter-only searches, or combine text and filters together.
 
 ```python
 # Filter-only — find all notes with a given status
-search_notes(metadata_filters={"status": "in-progress"})
+bm_search(filters={"status": "in-progress"}, project="<project>")
 
 # Filter-only — high-priority specs in a specific project
-search_notes(
-    metadata_filters={"type": "spec", "priority": {"$in": ["high", "critical"]}},
+bm_search(
+    filters={"type": "spec", "priority": {"$in": ["high", "critical"]}},
     project="research",
     page_size=10,
 )
 
 # Filter-only — notes with confidence above a threshold
-search_notes(metadata_filters={"confidence": {"$gt": 0.7}})
+bm_search(filters={"confidence": {"$gt": 0.7}}, project="<project>")
 
-# Convenience shortcuts for tags and status
-search_notes(status="active")
-search_notes(tags=["security", "oauth"])
+# Tags and status use the same filter syntax
+bm_search(filters={"status": "active"}, project="<project>")
+bm_search(filters={"tags": ["security", "oauth"]}, project="<project>")
 
 # Text search narrowed by metadata
-search_notes("authentication", metadata_filters={"status": "draft"})
+bm_search("authentication", filters={"status": "draft"}, project="<project>")
 
-# Mix text, tag shortcut, and advanced filter
-search_notes(
+# Mix text, tags, and an advanced filter
+bm_search(
     "oauth flow",
-    tags=["security"],
-    metadata_filters={"confidence": {"$gt": 0.7}},
+    filters={"tags": ["security"], "confidence": {"$gt": 0.7}},
+    project="<project>",
 )
 ```
 
-**Merging rules:** `tags` and `status` are convenience shortcuts merged into `metadata_filters` via `setdefault`. If the same key exists in `metadata_filters`, the explicit filter wins.
+Use one `filters` object for all frontmatter conditions; its keys combine with AND.
 
 ## Tag Search Shorthand
 
@@ -148,11 +159,11 @@ The `tag:` prefix in a query converts to a tag filter automatically:
 
 ```python
 # These are equivalent:
-search_notes("tag:tier1")
-search_notes("", tags=["tier1"])
+bm_search("tag:tier1", project="<project>")
+bm_search(filters={"tags": ["tier1"]}, project="<project>")
 
 # Multiple tags (comma or space separated) — all must match:
-search_notes("tag:tier1,alpha")
+bm_search("tag:tier1,alpha", project="<project>")
 ```
 
 ## Example: Custom Frontmatter in Practice
@@ -183,19 +194,19 @@ Queries that find it:
 
 ```python
 # By status and type
-search_notes(metadata_filters={"status": "in-progress", "type": "spec"})
+bm_search(filters={"status": "in-progress", "type": "spec"}, project="<project>")
 
 # By numeric threshold
-search_notes(metadata_filters={"confidence": {"$gt": 0.7}})
+bm_search(filters={"confidence": {"$gt": 0.7}}, project="<project>")
 
 # By priority set
-search_notes(metadata_filters={"priority": {"$in": ["high", "critical"]}})
+bm_search(filters={"priority": {"$in": ["high", "critical"]}}, project="<project>")
 
 # By tag shorthand
-search_notes("tag:security")
+bm_search("tag:security", project="<project>")
 
 # Combined text + metadata
-search_notes("OAuth", metadata_filters={"status": "in-progress"})
+bm_search("OAuth", filters={"status": "in-progress"}, project="<project>")
 ```
 
 ## Guidelines
@@ -204,6 +215,6 @@ search_notes("OAuth", metadata_filters={"status": "in-progress"})
 - **Use text search for content queries.** If you're looking for notes *about* something, text search is better. Combine both when you need precision.
 - **Custom fields are free.** Any YAML key you put in frontmatter becomes queryable — no schema or configuration required.
 - **Multiple filters are AND.** `{"status": "active", "priority": "high"}` requires both conditions.
-- **Omit `query` for filter-only searches.** `search_notes(metadata_filters={"status": "active"})` works without a text query.
+- **Omit `query` for filter-only searches.** `bm_search(filters={"status": "active"}, project="<project>")` works without a text query.
 - **Dot notation for nesting.** Access nested YAML structures with dots: `{"schema.version": "2"}` queries the `version` key inside a `schema` object.
-- **Tags shortcut is convenient but limited.** `tags` and `status` are sugar for common fields. For anything else, use `metadata_filters` directly.
+- **Use the same filters for file discovery.** `bm_find(filters={"status": "active"}, fields=["title", "priority"], project="<project>")` returns selected frontmatter values without reading each note.