memory-metadata-search

メモのメタデータ検索

メモの自由記述コンテンツではなく（またはそれに加えて）、構造化されたフロントマターのフィールドでメモを検索できます。メモのフロントマターにある標準キー（title、type、tags、permalink、schema）以外のカスタム YAML キーはすべて、自動的に entity_metadata としてインデックス化され、クエリで検索できるようになります。

使用する場面

• ステータスや優先度での絞り込み — status: draft または priority: high のメモをすべて検索します
• カスタムフィールドのクエリ — 独自に追加したフロントマターのキーはすべて検索できます
• 範囲クエリ — confidence > 0.7 または score between 0.3 and 0.8 のメモを検索します
• テキストとメタデータの組み合わせ — 構造化された条件を使ってテキスト検索を絞り込みます
• タグによる絞り込み — 特定のフロントマタータグが付いたメモを検索します
• スキーマを考慮したクエリ — ドット記法を使い、ネストされたスキーマフィールドで絞り込みます

ツール

ランキング順の結果には bm_search を、選択したフィールドを使ったファイルの検出には bm_find を使用します。タグやステータスを含むフロントマターの条件は filters で渡します。フィルターのみの検索では、query を省略するか、None を渡します。

フィルター構文

フィルターは JSON 辞書です。各キーはフロントマターのフィールドを指定し、値は一致条件を指定します。複数のキーは 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 との比較が true になることはありません。

ネストされたフィールドへのアクセス（ドット記法）

{"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_-]+ に一致する必要があります（ドットはネストの階層を区切ります）
• 1 つのフィールドに複数の演算子を指定した場合は AND 条件になります：{"started": {"$gte": "2026-01-01", "$lt": "2026-02-01"}}
• $in と配列に含まれる条件には、空でないリストが必要です
• $between には [min, max] の形式で、ちょうど 2 つの値が必要です
• null は null に一致する条件で、通常の等価値としてのみ使用できます
• 比較条件と $between の境界値は有限の数値である必要があります。浮動小数点数で表現できない大きさの値（JSON では通常の int として保持される 400 桁の整数など）は、無限大の境界値と比較するのではなく拒否されます
• メタデータフィルターは Markdown メモにのみ一致します。インデックス化された PDF、画像、その他の通常ファイルにはフロントマターがないため、null の条件であっても検索結果には含まれません

先頭の $ は省略できます（gte でも機能します）が、明確にするために付けることをおすすめします。

フロントマターのフィールドは、メモが記録またはレビューされた時期を示します。ある日付にメモが「真実だと主張していた」内容を尋ねるには、観測条件を使用します（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}},
)

すべてのフロントマター条件には、1 つの 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")

例：カスタムフロントマターの実例

カスタムフィールドを含むノート：

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

ガイドライン

• 構造化クエリにはメタデータ検索を使用します。 既知のフィールド値（ステータス、優先度、種類）でノートを探す場合、メタデータフィルターはテキスト検索よりも正確です。
• コンテンツのクエリにはテキスト検索を使用します。 あるトピックについて書かれたノートを探す場合、テキスト検索が適しています。精度が必要な場合は、両方を組み合わせます。
• カスタムフィールドは自由に追加できます。 フロントマターに記述した 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"]) は、各ノートを読み込まずに、選択したフロントマターの値を返します。