memory-metadata-search

记忆元数据搜索

按结构化的 Frontmatter 字段查找笔记，而不是（或除了）搜索自由文本内容。笔记 Frontmatter 中超出标准集合（title、type、tags、permalink、schema）的任何自定义 YAML 键，都会自动编入 entity_metadata 索引，并可供查询。

适用场景

• 按状态或优先级筛选 — 查找所有 status: draft 或 priority: high 的笔记
• 查询自定义字段 — 你自行定义的任何 Frontmatter 键都可搜索
• 范围查询 — 查找 confidence > 0.7 或 score 在 0.3 到 0.8 之间的笔记
• 组合文本与元数据 — 使用结构化条件缩小文本搜索范围
• 按标签筛选 — 查找带有特定 Frontmatter 标签的笔记
• 适配 Schema 的查询 — 使用点表示法按嵌套的 Schema 字段筛选

工具

使用 bm_search 获取排序后的结果，或使用 bm_find 按选定字段查找文件。通过 filters 传入 Frontmatter 条件，包括标签和状态。仅按筛选条件搜索时，可省略 query（或传入 None）。

筛选语法

筛选条件是一个 JSON 字典。每个键指定一个 Frontmatter 字段；对应的值指定匹配条件。多个键以 AND 逻辑组合。

相等

{"status": "active"}

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

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

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

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

比较（$gt、$gte、$lt、$lte）

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

数值使用数值比较；字符串使用字典序比较。

$between（包含边界值的范围）

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

Null（字段缺失或显式为 null）

{"owner": null}

匹配没有 owner 键的笔记，以及 owner 显式为 null 的笔记。 Null 仅可作为普通相等值使用——在 $in、$between、数组包含列表或比较中 会被拒绝，因为这些操作会比较具体的值，而与 null 的比较永远不会成立。

嵌套访问（点表示法）

{"schema.version": "2"}

快速参考

运算符	语法	示例
相等	{"field": "value"}	{"status": "active"}
为 null	{"field": null}	{"owner": null}
数组包含	{"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}}
嵌套	{"a.b": "value"}	{"schema.version": "2"}

规则：

• 键必须匹配 [A-Za-z0-9_-]+（点号用于分隔嵌套层级）
• 同一字段上的多个运算符以 AND 逻辑组合：{"started": {"$gte": "2026-01-01", "$lt": "2026-02-01"}}
• $in 和数组包含要求列表非空
• $between 必须恰好包含 [min, max]
• null 表示匹配 null，且仅可作为普通相等值使用
• 比较和 $between 的边界必须是有限数值——若数值大到任何浮点数都无法表示（例如 JSON 会保留为普通 int 的 400 位整数），则会被拒绝，而不会与无穷边界进行比较
• 元数据筛选仅匹配 Markdown 笔记——已编入索引的 PDF、图片和其他常规文件没有 Frontmatter，因此永远不会成为匹配项，即使筛选 null 也不例外

开头的 $ 可省略（gte 也可用），但建议保留以提高可读性。

Frontmatter 字段表示笔记的归档或审阅时间。若要询问笔记在某个日期 声称什么是真实的，请使用观察限定符（参见 memory-notes） 以及 bm_search(valid_at="2026-07-01") 或 bm_search(valid_overlaps="[2026-07-01,2026-08-01)")。

使用元数据调用 bm_search

将 filters 传递给 bm_search。仅按筛选条件搜索时，省略 query；也可以同时使用文本和筛选条件。

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

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

# Filter-only — notes with confidence above a threshold
bm_search(filters={"confidence": {"$gt": 0.7}})

# Tags and status use the same filter syntax
bm_search(filters={"status": "active"})
bm_search(filters={"tags": ["security", "oauth"]})

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

# Mix text, tags, and an advanced filter
bm_search(
    "oauth flow",
    filters={"tags": ["security"], "confidence": {"$gt": 0.7}},
)

所有 frontmatter 条件都使用同一个 filters 对象；其中的键按 AND 关系组合。

标签搜索简写

查询中的 tag: 前缀会自动转换为标签筛选条件：

# These are equivalent:
bm_search("tag:tier1")
bm_search(filters={"tags": ["tier1"]})

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

示例：实际使用自定义 Frontmatter

包含自定义字段的笔记：

---
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
bm_search(filters={"status": "in-progress", "type": "spec"})

# By numeric threshold
bm_search(filters={"confidence": {"$gt": 0.7}})

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

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

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

使用指南

• 结构化查询使用元数据搜索。 如果要按已知字段值（状态、优先级、类型）查找笔记，元数据筛选比文本搜索更精确。
• 内容查询使用文本搜索。 如果要查找关于某个主题的笔记，文本搜索更合适。需要提高精确度时，可组合使用两者。
• 自定义字段不受限制。 在 frontmatter 中添加的任何 YAML 键都可用于查询，无需架构或配置。
• 多个筛选条件按 AND 关系组合。 {"status": "active", "priority": "high"} 要求同时满足这两个条件。
• 仅按筛选条件搜索时，省略 query。 bm_search(filters={"status": "active"}) 无需文本查询即可使用。
• 嵌套结构使用点表示法。 使用点号访问嵌套的 YAML 结构：{"schema.version": "2"} 会查询 schema 对象中的 version 键。
• 使用相同的筛选条件查找文件。 bm_find(filters={"status": "active"}, fields=["title", "priority"]) 会返回选定的 frontmatter 值，无需读取每篇笔记。