Memory Metadata Search

title

type

tags

permalink

schema

entity_metadata

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

search_notes

metadata_filters

tags

status

query

None

Filter Syntax

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}}

$between

(inclusive range)

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

Nested Access (dot notation)

{"schema.version": "2"}

Quick Reference

{"field": "value"}

{"status": "active"}

{"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]}}

{"a.b": "value"}

{"schema.version": "2"}

• 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]

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

metadata_filters

tags

status

search_notes

query

# 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
search_notes(metadata_filters={"confidence": {"$gt": 0.7}})

# Convenience shortcuts for tags and status
search_notes(status="active")
search_notes(tags=["security", "oauth"])

# Text search narrowed by metadata
search_notes("authentication", metadata_filters={"status": "draft"})

# Mix text, tag shortcut, and advanced filter
search_notes(
    "oauth flow",
    tags=["security"],
    metadata_filters={"confidence": {"$gt": 0.7}},
)

tags

status

metadata_filters

setdefault

metadata_filters

Tag Search Shorthand

tag:

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

Example: Custom Frontmatter in Practice

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

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.