# Memory Metadata Search

Search Basic Memory notes by custom frontmatter fields with equality, range, array, and...

- Repository: https://github.com/basicmachines-co/basic-memory (4440 stars)
- Category: Writing
- 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 memory-metadata-search -g -a claude-code -y`
Codex: `npx skills add basicmachines-co/basic-memory --skill memory-metadata-search -g -a codex -y`
Cursor: `npx skills add basicmachines-co/basic-memory --skill memory-metadata-search -g -a cursor -y`
Gemini CLI: `npx skills add basicmachines-co/basic-memory --skill memory-metadata-search -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add basicmachines-co/basic-memory`

## Description

Search Basic Memory notes by custom frontmatter fields with equality, range, array, and nested filters. Use when finding notes by status, priority, confidence, or any YAML field, not free text.

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

# Memory Metadata Search

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`
- **Querying custom fields**, any frontmatter key you invent is searchable
- **Range queries**, find notes with `confidence > 0.7` or `score between 0.3 and 0.8`
- **Combining text + metadata**, narrow a text search with structured constraints
- **Tag-based filtering**, find notes tagged with specific frontmatter tags
- **Schema-aware queries**, filter by nested schema fields using dot notation

## The Tool

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

Filters are a JSON dictionary. Each key targets a frontmatter field; the value specifies the match condition. Multiple keys combine with **AND** logic.

### Equality

```json
{"status": "active"}
```

### Array Contains (all listed values must be present)

The rest: https://github.com/basicmachines-co/basic-memory/blob/HEAD/skills/memory-metadata-search/SKILL.md