memory-schema

メモリスキーマ

Basic Memory の Picoschema システムを使用して、構造化されたノートの種類を管理します。スキーマは、ノートの種類に含めるフィールドを定義し、ノートの形式を統一して、検索や検証を可能にします。

使用するタイミング

• 新しいノートの種類が生まれたとき — 複数のノートが同じ構造（会議、人物、決定事項など）を共有していることに気づいたとき
• 検証チェック — 既存のノートがスキーマに準拠していることを確認するとき
• スキーマのずれ — スキーマで定義されていないフィールドがノートで使われている場合（またはその逆）に検出するとき
• スキーマの進化 — 要件の変化に応じてフィールドを追加、削除、変更するとき
• 必要に応じて — ユーザーがスキーマの作成、チェック、管理を依頼したとき

Picoschema 構文リファレンス

スキーマは、ノートの構造を記述する簡潔な記法である Picoschema を使い、YAML フロントマターで定義します。

基本型

schema:
  name: string, person's full name
  age: integer, age in years
  score: number, floating-point rating
  active: boolean, whether currently active

サポートされている型：string、integer、number、boolean。

任意フィールド

フィールド名の末尾に ? を付けます。

schema:
  title: string, required field
  subtitle?: string, optional field

列挙型

許可する値のリストを指定して (enum) を使います。

schema:
  status(enum, current state): [active, blocked, done, abandoned]

任意の列挙型：

schema:
  priority?(enum, task priority): [low, medium, high, critical]

配列

リスト形式のフィールドには (array) を使います。

schema:
  tags(array): string, categorization labels
  steps?(array): string, ordered steps to complete

リレーション

他のエンティティ型を直接参照します。

schema:
  parent_task?: Task, parent task if this is a subtask
  attendees?(array): Person, people who attended

リレーションはナレッジグラフにエッジを作成し、ノート同士をリンクします。

検証設定

settings:
  validation: warn    # warn (log issues) or strict (errors)

強制モードの標準として strict を使用します。error は互換性のためのエイリアスとしてのみ受け付けられます。

完全な例

---
title: Meeting
type: schema
entity: Meeting
version: 1
schema:
  topic: string, what was discussed
  date: string, when it happened (YYYY-MM-DD)
  attendees?(array): Person, who attended
  decisions?(array): string, decisions made
  action_items?(array): string, follow-up tasks
  status?(enum, meeting state): [scheduled, completed, cancelled]
settings:
  validation: warn
---

スキーマが定義されていないノートの検出

構造を共有しながらスキーマがないノートのまとまりを探します。

1. 種類で検索：bm_search(note_types=["meeting"]) — 多くのノートが type を共有しているのに schema/Meeting.md が存在しない場合、候補になります。

2. スキーマを推測：bm_schema(command="infer") を使って既存のノートを分析し、スキーマ案を生成します。

   bm_schema(command="infer", note_type="Meeting")
   bm_schema(command="infer", note_type="Meeting", threshold=0.5)  # fields in 50%+ of notes
   

   しきい値（0.0～1.0）は、フィールドを含めるために必要な出現頻度を制御します。通常はデフォルトのままで問題ありません。より珍しいフィールドも検出するには、しきい値を下げます。

3. 提案を確認 — 推測されたスキーマには、フィールド名、型、出現頻度が表示されます。どのフィールドを残すか、任意にするか、削除するかを決めます。

スキーマの作成

スキーマノートを schema/<EntityName> に書き込みます。

bm_write(
  title="Meeting",
  directory="schema",
  note_type="schema",
  metadata={
    "entity": "Meeting",
    "version": 1,
    "schema": {
      "topic": "string, what was discussed",
      "date": "string, when it happened",
      "attendees?(array)": "Person, who attended",
      "decisions?(array)": "string, decisions made"
    },
    "settings": {"validation": "warn"}
  },
  content="""# Meeting

Schema for meeting notes.

## Observations
- [convention] Meeting notes live in memory/meetings/ or as daily entries
- [convention] Always include date and topic
- [convention] Action items should become tasks when complex"""
)

重要な原則

• スキーマノートは schema/ に保存します — エンティティ型ごとに1つのノートを作成します
• note_type="schema" は、ノートをスキーマ定義として指定します
• メタデータの entity: Meeting は、適用対象の型を指定します
• メタデータの version: 1 — 破壊的変更を行うときに値を増やします
• settings.validation: warn から始めることを推奨します — 書き込みをブロックせずに問題をログに記録します

ノートの検証

既存のノートがスキーマにどの程度準拠しているかを確認します。

# Validate all notes of a type
bm_schema(command="validate", note_type="Meeting")

# Validate a single note
bm_schema(command="validate", identifier="meetings/2026-02-10-standup")

重要： bm_schema(command="validate") は、ノート本文内の観測カテゴリとしてスキーマのフィールドをチェックします。たとえば、status フィールドには、観測として - [status] active が必要です。フロントマターのメタデータにのみ保存されたフィールドは、検証を満たしません。問題なく検証を通過するには、スキーマのフィールドをフロントマターの値（メタデータ検索用）と観測（スキーマ検証用）の両方に含めます。

検証結果には、必須フィールドの欠落（観測カテゴリ、またはエンティティ参照フィールドの場合はリレーション）と、無効な列挙値が報告されます。宣言されていない観測カテゴリとリレーションは、情報提供用の「一致しない項目」として一覧表示されます。スカラー値の型はチェックされません。

検証結果への対応

• warn モード：警告を定期的に確認します。明らかに誤っているノートは修正し、正当な新しいパターンがある場合は任意フィールドをスキーマに追加します。
• strict モード：ノートの準拠が重要な場面（ノートを処理する自動パイプラインなど）で使用します。

ずれの検出

時間が経つにつれてノートは変化し、スキーマが追いつかなくなることがあります。bm_schema(command="diff") を使って相違を見つけます。

bm_schema(command="diff", note_type="Meeting")

差分レポートには、次の内容が含まれます。

• スキーマにはないがノートにあるフィールド — スキーマへの追加候補（任意フィールドとして）
• 使用頻度の低いスキーマフィールド — 任意にするか、削除することを検討します
• 多重度の変更 — 単一値と配列の間で変化したフィールド

スキーマの進化

ノートの構造を変更する場合：

1. 差分を実行して現在の状態を確認します：bm_schema(command="diff", note_type="Meeting")
2. metadata パラメーターを指定して bm_edit でスキーマノートを更新します。トップレベルのキーは全体が置き換えられるため、更新後の schema マップ全体と新しい version を渡してください：

   bm_edit(
     identifier="schema/Meeting",
     command="set_metadata",
     metadata={
       "version": 2,
       "schema": {
         "topic": "string, what was discussed",
         "date": "string, when it happened",
         "attendees?(array)": "Person, who attended",
         "decisions?(array)": "string, decisions made",
         "location?": "string, where it happened"
       }
     }
   )
   

3. 再検証して、既存のノートが引き続き検証に通ることを確認します：bm_schema(command="validate", note_type="Meeting")
4. 逸脱したノートを修正します — 新しいスキーマに準拠しないノートを更新してください

進化のガイドライン

• 追加的な変更（新しい任意項目）は安全です — バージョンを上げる必要はありません
• 破壊的変更（新しい必須項目、項目の削除、型の変更）では version を上げてください
• 必須より任意を優先してください — ほとんどの項目は、まず任意にしてください
• 制約を厳しくしすぎないでください — スキーマは一般的な構造を記述するものであり、厳格なテンプレートを強制するものではありません
• ドキュメントとしてのスキーマ — 検証が warn に設定されていても、スキーマはその種類のノートに含めるべき内容を示す、生きたドキュメントとして機能します

ワークフローの概要

1. Notice repeated note structure → infer schema (bm_schema(command="infer"))
2. Review + create schema note   → write to schema/ (bm_write)
3. Validate existing notes       → check conformance (bm_schema(command="validate"))
4. Fix outliers                  → edit non-conforming notes (bm_edit)
5. Periodically check drift      → detect divergence (bm_schema(command="diff"))
6. Evolve schema as needed       → update schema note (bm_edit)