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": {"$in": ["high", "critical"]}}

Comparisons ($gt, $gte, $lt, $lte)

{"confidence": {"$gt": 0.7}}

Numeric values use numeric comparison; strings use lexicographic comparison.

$between (inclusive range)

{"score": {"$between": [0.3, 0.8]}}

Null (field missing or explicitly null)

{"owner": 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)

{"schema.version": "2"}

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]}}
$contains	{"field": {"$contains": value}}	{"tags": {"$contains": "security"}}
$exists	{"field": {"$exists": true}}	{"owner": {"$exists": false}}
Nested	{"a.b": "value"}	{"schema.version": "2"}

Rules:

• Keys must match [A-Za-z0-9_-]+ (dots separate nesting levels)
• Several operators on one field AND together: {"started": {"$gte": "2026-01-01", "$lt": "2026-02-01"}}
• $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

The leading $ is optional (gte works), but write it for clarity.

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)").

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.

# Filter-only — find all notes with a given status
search_notes(metadata_filters={"status": "in-progress"})

# Filter-only — high-priority specs in a specific project
search_notes(
    metadata_filters={"type": "spec", "priority": {"$in": ["high", "critical"]}},
    project="research",
    page_size=10,
)

# Filter-only — notes with confidence above a threshold

**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:

```python
# These are equivalent:
search_notes("tag:tier1")
search_notes("", tags=["tier1"])

# Multiple tags (comma or space separated) — all must match:
search_notes("tag:tier1,alpha")

---
title: Auth Design
type: spec
tags: [security, oauth]
status: in-progress
priority: high
confidence: 0.85
---

# Auth Design

## Observations
- [decision] Use OAuth 2.1 with PKCE for all client types #security
- [requirement] Token refresh must be transparent to the user

## Relations
- implements [[Security Requirements]]

# By status and type
search_notes(metadata_filters={"status": "in-progress", "type": "spec"})

# By numeric threshold
search_notes(metadata_filters={"confidence": {"$gt": 0.7}})

# By priority set
search_notes(metadata_filters={"priority": {"$in": ["high", "critical"]}})

# By tag shorthand
search_notes("tag:security")

# Combined text + metadata
search_notes("OAuth", metadata_filters={"status": "in-progress"})