memory-metadata-search

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

{"status": "active"}

Array Contains (all listed values must be present)

{"tags": ["security", "oauth"]}

$in (match any value in list)

{"priority"

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

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.