memory-metadata-search

Memory メタデータ検索

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

使用する場面

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

ツール

メタデータ検索にはすべて search_notes を使用します。metadata_filters でフィルターを渡すか、簡易指定の tags と status を使用します。フィルターのみで検索する場合は、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]}}

ネストへのアクセス（ドット記法）

{"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_-]+ に一致する必要があります（ドットはネストの階層を区切ります）
• 演算子の辞書には演算子をちょうど1つ含める必要があります
• $in と配列に含まれる条件には、空でないリストが必要です
• $between には [min, max] をちょうど1つ指定する必要があります

警告： 演算子には必ず $ 接頭辞を付けてください。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")

例：カスタムフロントマターの実際の使い方

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

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

ガイドライン

• 構造化クエリにはメタデータ検索を使用します。 既知のフィールド値（ステータス、優先度、種類）でノートを探す場合は、メタデータフィルターのほうがテキスト検索よりも正確です。
• 内容に関するクエリにはテキスト検索を使用します。 ある事柄 について 書かれたノートを探す場合は、テキスト検索のほうが適しています。精度が必要な場合は、両方を組み合わせてください。
• カスタムフィールドは自由に使えます。 YAML のフロントマターに追加したキーはすべてクエリ可能です。スキーマや設定は必要ありません。
• 複数のフィルターは AND 条件です。 {"status": "active", "priority": "high"} は、両方の条件を満たす必要があります。
• フィルターのみの検索では query を省略します。 search_notes(metadata_filters={"status": "active"}) は、テキストクエリなしで実行できます。
• ネストされた構造にはドット記法を使用します。 ドットを使ってネストされた YAML 構造にアクセスします。{"schema.version": "2"} は、schema オブジェクト内の version キーを検索します。
• タグのショートカットは便利ですが、用途が限られます。 tags と status は、よく使われるフィールドの簡易記法です。それ以外のフィールドには、metadata_filters を直接使用してください。