Structured metadata search for Basic Memory: query notes by custom frontmatter fields using equality, range, array, and nested filters. Use when finding notes by status, priority, confidence, or any custom YAML field rather than free-text content.

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. 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 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. 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 Array Contains (all listed values must be present) $in (match any value in list) Comparisons ( $gt , $gte , $lt , $lte ) Numeric values use numeric comparison; strings use lexicographic comparison. $between (inclusive range) Null (field missing or explicitly null) Matches notes with no owner key and notes whose owner is explicitly null. Null works only as a plain equality value — inside $in , $between , an array contains list, or a comparison it is rejected, because those compare against the value and a comparison with null is never true. Nested Access (dot notation) Quick Reference Operator Syntax Example Equality {"field": "value"} {"status": "active"} Is null {"field": null} {"owner": null} Array contains {"field": ["a", "b"]} {"tags": ["security", "oauth"]} $in {"field": {"$in": [...]}} {"priority": {"$in": ["high", "critical"]}} $gt / $gte {"field": {"$gt": N}} {"confidence": {"$gt": 0.7}} $lt / $lte {"field": {"$lt": N}} {"score": {"$lt": 0.5}} $between {"field": {"$between": [lo, hi]}} {"score": {"$between": [0.3, 0.8]}} Nested {"a.b": "value"} {"schema.version": "2"} Rules: Keys must match [A Za z0 9 ]+ (dots separate nesting levels) Operator dicts must contain exactly one operator $in and array contains require non empty lists $between requires exactly [min, max] null is an is null match and only valid as a plain equality value Comparison and $between bounds must be finite numbers — a magnitude no float can hold (a 400 digit integer, which JSON keeps as an ordinary int ) is refused rather than compared against an infinite bound Metadata filters match Markdown notes only — indexed PDFs, images and other regular files carry no frontmatter and are never hits, not even for null Warning: Operators MUST include the $ prefix — write $gte , not gte . Without the prefix the filter is treated as an exact match key and will silently return no results. Correct: {"confidence": {"$gte": 0.7}} . Wrong: {"confidence": {"gte": 0.7}} . Using search notes with Metadata Pass metadata filters , tags , or status to search notes . Omit query for filter only searches, or combine text and filters together. 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. Tag Search Shorthand The tag: prefix in a query converts to a tag filter automatically: Example: Custom Frontmatter in Practice A note with custom fields: Queries that find it: Guidelines Use metadata search for structured queries. If you're looking for notes by a known field value (status, priority, type), metadata filters are more precise than text search. 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. 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.

memory-metadata-search