memory-metadata-search

记忆元数据搜索

通过笔记的结构化 frontmatter 字段（而非仅靠自由文本内容，或在此基础上额外）查找笔记。笔记 frontmatter 中除标准集合（title、type、tags、permalink、schema）之外的任何自定义 YAML 键都会自动被索引为 entity_metadata，并可被查询。

何时使用

• 按状态或优先级筛选 — 查找所有 status: draft 或 priority: high 的笔记
• 查询自定义字段 — 你发明的任何 frontmatter 键都可搜索
• 范围查询 — 查找 confidence > 0.7 或 score between 0.3 and 0.8 的笔记
• 组合文本 + 元数据 — 用结构化约束缩小文本搜索范围
• 基于标签的筛选 — 查找带有特定 frontmatter 标签的笔记
• 感知 schema 的查询 — 使用点号表示法按嵌套 schema 字段筛选

工具

所有元数据搜索都使用 search_notes。通过 metadata_filters 传入筛选条件，或使用 tags 和 status 便捷快捷方式。仅进行筛选搜索时可省略 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]}}

嵌套访问（点号表示法）

{"schema.version": "2"}

快速参考

运算符	语法	示例
相等	{"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}}。

将 search_notes 与元数据配合使用

将 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 是通过 setdefault 合并到 metadata_filters 中的便捷快捷方式。如果 metadata_filters 中存在相同的键，则以显式筛选条件为准。

标签搜索简写

查询中的 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")

示例：自定义 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
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"})

指南

• 结构化查询请使用元数据搜索。 如果你要按已知字段值（状态、优先级、类型）查找笔记，元数据过滤器比文本搜索更精确。
• 内容查询请使用文本搜索。 如果你要查找关于某事物的笔记，文本搜索更合适。需要精确性时，可同时结合两者。
• 自定义字段是自由的。 你在 frontmatter 中放入的任何 YAML 键都会变为可查询的——无需 schema 或配置。
• 多个过滤器之间是 AND 关系。 {"status": "active", "priority": "high"} 要求两个条件同时满足。
• 仅按过滤器搜索时省略 query。 search_notes(metadata_filters={"status": "active"}) 无需文本查询即可使用。
• 嵌套使用点号表示法。 用点号访问嵌套的 YAML 结构：{"schema.version": "2"} 查询 schema 对象内的 version 键。
• 标签快捷方式方便但有限。 tags 和 status 是常见字段的语法糖。其他任何内容，请直接使用 metadata_filters。