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): [active, blocked, done, abandoned], current state

オプションの列挙型：

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

配列

リスト型のフィールドには (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 error (strict)

完全な例

---
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): [scheduled, completed, cancelled], meeting state
settings:
  validation: warn
---

スキーマがないノートを見つける

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

1. 種類で検索する：search_notes(query="type:Meeting") — 多くのノートが同じ type を共有していて、schema/Meeting.md が存在しない場合、候補となります。

2. スキーマを推定する：schema_infer を使って既存のノートを分析し、推奨スキーマを生成します。

   schema_infer(noteType="Meeting")
   schema_infer(noteType="Meeting", threshold=0.5)  # fields in 50%+ of notes
   

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

3. 推奨内容を確認する — 推定されたスキーマには、フィールド名、型、出現頻度が表示されます。どのフィールドを残すか、オプションにするか、削除するかを判断します。

スキーマの作成

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

write_note(
  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
schema_validate(noteType="Meeting")

# Validate a single note
schema_validate(identifier="meetings/2026-02-10-standup")

重要： schema_validate は、ノート本文にあるスキーマフィールドを観察カテゴリとして確認します。たとえば、status フィールドでは、観察として - [status] active が必要です。フロントマターのメタデータだけに保存されたフィールドは、検証を満たしません。検証に問題なく通過するには、メタデータ検索用のフロントマター値と、スキーマ検証用の観察の両方にスキーマフィールドを含めてください。

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

• 必須フィールドの不足 — スキーマで必須とされているフィールドがノートにありません（観察カテゴリとして）
• 未知のフィールド — スキーマで定義されていないフィールドがノートにあります
• 型の不一致 — フィールド値が期待される型と一致しません
• 無効な列挙値 — 値が許可された値の一覧にありません

検証結果への対応

• warn モード：警告を定期的に確認します。明らかに誤っているノートを修正し、正当な新しいパターンにはオプションのフィールドをスキーマに追加します。
• error モード：ノートを利用する自動パイプラインなど、準拠が重要となる厳格なスキーマで使用します。

ずれの検出

時間の経過とともにノートは変化し、スキーマが追いつかなくなることがあります。schema_diff を使って差異を見つけます。

schema_diff(noteType="Meeting")

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

• ノートにはあるがスキーマにはないフィールド — （オプションとして）スキーマへの追加候補です
• 使用頻度の低いスキーマフィールド — オプションにするか、削除することを検討します
• 型の不整合 — ノートによって異なる型で使われているフィールドです

スキーマの進化

ノートの構造が変わったとき：

1. 差分を実行して現在の状態を確認します：schema_diff(noteType="Meeting")
2. edit_note を使ってスキーマノートを更新します：

   edit_note(
     identifier="schema/Meeting",
     operation="find_replace",
     find_text="version: 1",
     content="version: 2",
     expected_replacements=1
   )
   

3. schema: ブロックのフィールドを追加／削除／変更します
4. 再検証して、既存のノートが引き続き合格することを確認します：schema_validate(noteType="Meeting")
5. 例外を修正します — 新しいスキーマに準拠しないノートを更新します

進化のガイドライン

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

ワークフローの概要

1. Notice repeated note structure → infer schema (schema_infer)
2. Review + create schema note   → write to schema/ (write_note)
3. Validate existing notes       → check conformance (schema_validate)
4. Fix outliers                  → edit non-conforming notes (edit_note)
5. Periodically check drift      → detect divergence (schema_diff)
6. Evolve schema as needed       → update schema note (edit_note)