Back to Details

memory-metadata-search

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Memory Metadata Search

Memory元数据搜索

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.
通过结构化前置元数据字段查找笔记，可替代或结合自由文本内容搜索。笔记前置元数据中，除标准字段（
title
、
type
、
tags
、
permalink
、
schema
）外的任何自定义YAML键，都会自动被索引为
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
  • 按状态或优先级筛选 — 查找所有带有
    status: draft
    或
    priority: high
    的笔记
  • 查询自定义字段 — 你自定义的任何前置元数据键都可搜索
  • 范围查询 — 查找
    confidence > 0.7
    或
    score
    在0.3到0.8之间的笔记
  • 文本+元数据组合查询 — 用结构化约束缩小文本搜索范围
  • 基于标签的筛选 — 查找带有特定前置元数据标签的笔记
  • 感知Schema的查询 — 使用点符号筛选嵌套Schema字段

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.
所有元数据搜索都使用
search_notes
函数。通过
metadata_filters
传入筛选器，或使用
tags
和
status
快捷方式。省略
query
（或传入
None
）即可仅使用筛选器进行搜索。

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.
筛选器是一个JSON字典。每个键对应一个前置元数据字段；值指定匹配条件。多个键之间为AND逻辑关系。

Equality

相等匹配

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

Array Contains (all listed values must be present)

数组包含（需包含所有列出的值）

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

$in
(match any value in list)

$in
（匹配列表中的任意值）

json
{"priority": {"$in": ["high", "critical"]}}
json
{"priority": {"$in": ["high", "critical"]}}

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

比较运算（
$gt
, 
$gte
, 
$lt
, 
$lte
）

json
{"confidence": {"$gt": 0.7}}
Numeric values use numeric comparison; strings use lexicographic comparison.
json
{"confidence": {"$gt": 0.7}}
数值使用数值比较；字符串使用字典序比较。

$between
(inclusive range)

$between
（包含范围）

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

Nested Access (dot notation)

嵌套访问（点符号）

json
{"schema.version": "2"}
json
{"schema.version": "2"}

Quick Reference

速查表

OperatorSyntaxExample
Equality
{"field": "value"}
{"status": "active"}
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]
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}}
.
运算符语法示例
相等匹配
{"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"}
规则：
  • 键必须匹配
    [A-Za-z0-9_-]+
    （点符号用于分隔嵌套层级）
  • 运算符字典必须恰好包含一个运算符
  • $in
    和数组包含要求列表非空
  • $between
    要求恰好为
    [min, max]
    格式
注意： 运算符必须包含
$
前缀 — 请写
$gte
而非
gte
。如果没有前缀，筛选器会被当作精确匹配的键处理，且会静默返回空结果。正确写法：
{"confidence": {"$gte": 0.7}}
。错误写法：
{"confidence": {"gte": 0.7}}
。

Using 
search_notes
with Metadata

结合元数据使用
search_notes

Pass 
metadata_filters
, 
tags
, or 
status
to 
search_notes
. Omit 
query
for filter-only searches, or combine text and filters together.
python
undefined
向
search_notes
传入
metadata_filters
、
tags
或
status
。省略
query
即可仅使用筛选器搜索，也可将文本搜索与筛选器结合使用。
python
undefined

Filter-only — find all notes with a given status

仅筛选 — 查找所有带有指定状态的笔记

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

Convenience shortcuts for tags and status

tags和status的快捷方式

search_notes(status="active") search_notes(tags=["security", "oauth"])
search_notes(status="active") search_notes(tags=["security", "oauth"])

Text search narrowed by metadata

结合文本搜索与元数据筛选

search_notes("authentication", metadata_filters={"status": "draft"})
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}}, )

**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.
search_notes( "oauth flow", tags=["security"], metadata_filters={"confidence": {"$gt": 0.7}}, )

**合并规则：** `tags`和`status`是快捷方式，会通过`setdefault`合并到`metadata_filters`中。如果`metadata_filters`中存在相同的键，则显式指定的筛选器优先级更高。

Tag Search Shorthand

标签搜索简写

The 
tag:
prefix in a query converts to a tag filter automatically:
python
undefined
查询中的
tag:
前缀会自动转换为标签筛选器：
python
undefined

These are equivalent:

以下两种写法等价：

search_notes("tag:tier1") search_notes("", tags=["tier1"])
search_notes("tag:tier1") search_notes("", tags=["tier1"])

Multiple tags (comma or space separated) — all must match:

多个标签（逗号或空格分隔）—— 必须同时匹配：

search_notes("tag:tier1,alpha")
undefined
search_notes("tag:tier1,alpha")
undefined

Example: Custom Frontmatter in Practice

示例：自定义前置元数据的实际应用

A note with custom fields:
markdown
---
title: Auth Design
type: spec
tags: [security, oauth]
status: in-progress
priority: high
confidence: 0.85
---
带有自定义字段的笔记：
markdown
---
title: Auth Design
type: spec
tags: [security, oauth]
status: in-progress
priority: high
confidence: 0.85
---

Auth Design

Auth Design

Observations

观察结果

  • [decision] Use OAuth 2.1 with PKCE for all client types #security
  • [requirement] Token refresh must be transparent to the user
  • [决策] 对所有客户端类型使用带有PKCE的OAuth 2.1 #security
  • [需求] Token刷新需对用户透明

Relations

关联内容

  • implements [[Security Requirements]]

Queries that find it:

```python
  • 实现 [[Security Requirements]]

可找到该笔记的查询示例：

```python

By status and type

按状态和类型筛选

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

By numeric threshold

按数值阈值筛选

search_notes(metadata_filters={"confidence": {"$gt": 0.7}})
search_notes(metadata_filters={"confidence": {"$gt": 0.7}})

By priority set

按优先级集合筛选

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

By tag shorthand

通过标签简写搜索

search_notes("tag:security")
search_notes("tag:security")

Combined text + metadata

结合文本搜索与元数据筛选

search_notes("OAuth", metadata_filters={"status": "in-progress"})
undefined
search_notes("OAuth", metadata_filters={"status": "in-progress"})
undefined

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.
  • 结构化查询使用元数据搜索。如果你需要通过已知字段值（状态、优先级、类型）查找笔记，元数据筛选器比文本搜索更精准。
  • 内容查询使用文本搜索。如果你需要查找与某主题相关的笔记，文本搜索更合适。当需要精准结果时，可结合两者使用。
  • 自定义字段不受限制。你添加到前置元数据中的任何YAML键都支持查询 — 无需配置Schema或进行其他设置。
  • 多个筛选器为AND关系。
    {"status": "active", "priority": "high"}
    要求同时满足两个条件。
  • 仅筛选搜索可省略
    query
    。
    search_notes(metadata_filters={"status": "active"})
    无需文本查询即可生效。
  • 嵌套结构使用点符号。使用点符号访问嵌套YAML结构：
    {"schema.version": "2"}
    用于查询
    schema
    对象中的
    version
    键。
  • 标签快捷方式便捷但有局限。
    tags
    和
    status
    是针对常见字段的语法糖。对于其他字段，请直接使用
    metadata_filters
    。