memory-notes

メモ

Basic Memory が解析して検索可能なナレッジグラフを作成できるよう、構造化されたメモを作成します。各メモは、フロントマター、観察事項、関係という3つの主要セクションを持つ Markdown ファイルです。

メモの構成

---
title: API Design Decisions
tags: [api, architecture, decisions]
---

# API Design Decisions

The API team evaluated multiple approaches for the public API during Q1. After
prototyping both REST and GraphQL, the team chose REST due to broader ecosystem
support and simpler caching semantics. This note captures the key decisions and
their rationale, along with open questions still to resolve.

## Observations
- [decision] Use REST over GraphQL for simplicity #api
- [requirement] Must support versioning from day one
- [risk] Rate limiting needed for public endpoints

## Relations
- implements [[API Specification]]
- depends_on [[Authentication System]]
- relates_to [[Performance Requirements]]

フロントマター

各メモは YAML フロントマターから始まります。

---
title: Note Title          # required — becomes the entity name in the knowledge graph
tags: [tag1, tag2]         # optional — for organization and filtering
type: note                 # optional — defaults to "note", use custom types with schemas
permalink: custom-path     # optional — auto-generated from title if omitted
---

• title は本文の # Heading と一致させる必要があります
• タグは検索可能で、情報の発見に役立ちます
• カスタムの type 値（Task、Meeting、Person など）はスキーマシステムで使用できます。スキーマの定義、メモの検証、差異の検出については、memory-schema スキルを参照してください。
• permalink は title と directory から自動生成されます。たとえば、ディレクトリが specs の場合、タイトル「API Design Decisions」からパーマリンク specs/api-design-decisions とメモ URL memory://specs/api-design-decisions が生成されます。ディレクトリが指定されていない場合、パーマリンクはハイフン区切りにしたタイトルのみになります。デフォルトでは、ファイルを移動してもパーマリンクは変更されません（プロジェクトで update_permalinks_on_move が有効になっている場合を除きます）。手動で設定する必要はほとんどありません。

注： write_note を使用する場合、フロントマターは自分で記述しません。title、tags、note_type、metadata はそれぞれ別のパラメーターで指定し、Basic Memory がフロントマターを自動生成します。content パラメーターには、# Heading で始まる Markdown 本文だけを指定します。

本文／コンテキスト

見出しと「観察事項」セクションの間に記述する自由形式の Markdown です。メモの中心となる部分なので、十分に詳しく記述してください。

• 背景、動機、経緯
• 何が起きたのか、なぜ重要なのかについての詳細な説明
• 検討した分析、推論、トレードオフ
• 後からこのメモを読む人（または AI）が理解するために必要なコンテキスト

内容のある完全な文章で記述してください。Basic Memory の検索ではメモ本文から関連するチャンクが取得されるため、コンテキストが長く豊富であるほど、メモが見つかりやすく、見つかったときにも役立ちます。すべてを箇条書きにせず、経緯が伝わるように記述してください。

観察事項

観察事項は、カテゴリ分けされた事実、つまり知識を構成する最小単位です。それぞれがナレッジグラフ内の検索可能なエンティティになります。

構文

- [category] Content of the observation #optional-tag

• 角括弧で意味カテゴリを定義します
• 内容には事実、決定事項、洞察、メモを記述します
• ハッシュタグ（任意）で、フィルタリング用の追加メタデータを指定します

カテゴリは自由に設定できます

角括弧内のカテゴリは自由形式で、観察事項に適したラベルを使えます。固定のリストはありません。ルールは [category] content という構文だけです。プロジェクト内で一貫性を保つと検索しやすくなりますが、カテゴリは自由に作成してください。

幅広い使い方を示す例をいくつか紹介します。

- [decision] Use PostgreSQL for primary data store
- [risk] Third-party API has no SLA guarantee
- [technique] Exponential backoff for retry logic #resilience
- [question] Should we support multi-tenancy at the DB level?
- [preference] Use Bun over Node for new projects
- [lesson] Always validate webhook signatures server-side
- [status] active
- [flavor] Ethiopian beans work best with lighter roasts

観察事項を記述する際のヒント

• 観察事項ごとに事実を1つ記述します。 1行に複数の考えを詰め込まないでください。
• 具体的に記述します。 [decision] Use JWT よりも、[decision] Use JWT with 15-minute expiry for API auth の方が役立ちます。
• 横断的な懸念事項にはタグを使用します。 [risk] Rate limiting needed #api #security とすると、両方のトピックから見つけられます。
• カテゴリはクエリで指定できます。 search_notes(entity_types=["observation"], categories=["decision"]) を実行すると、ナレッジベース全体の決定事項の観察がすべて返されます。

主張が成り立つ時期

観察には、それがいつ真実であるかを示せます。カテゴリの後に修飾子を指定します。

- [decision] @effective:2026-06-10 The cache layer uses Redis
- [event] @occurred:2026-10-14 Launch sync moved the date to Thursday
- [deadline] @due:2026-10-20 Draft ready for review
- [stage] @valid:2026-10 Series B, about 200 employees
- [decision] @effective[2026-06-10,2026-10-14) Launch on Friday

• 種類：effective（決定または規則が発効する）、occurred（イベントが発生した）、due（約束の期限）、mentioned（発言された時点）、およびデフォルトのvalid（@2026-06-10は@valid:2026-06-10を意味します）。
• 時点は、指定した精度が示す期間を対象とします。@2026はその年、@2026-06はその月、@2026-06-10はその日以降です。
• 範囲には[start,end)を使用します。開始または終了のどちらも省略できます：@effective[2026-06-10,)。
• 日付は明記します。引用符のない日付は1つのトークンです（@occurred:2026-06-10）。それより長い表記には引用符を付けます：@occurred:"June 10, 2026"。yesterdayのような相対日付は修飾子として解釈されず、テキスト内にそのまま残ります。
• 事実が変わったときは、古い範囲を閉じて新しい範囲を開始し、古い事実を削除しないでください。どちらも日付で検索できます。

ノートが真実だったと述べている時期で検索し、編集された時期では検索しないようにします。

search_notes(valid_at="2026-07-01")                              # true on that date
search_notes(time_kind="due", valid_overlaps="[2026-10-14,2026-10-21)")  # due this week

有効時刻フィルターは、日付が指定された観察のみを返します。すべてを検索するには、このフィルターを外します。日単位の時点は「その日以降」を対象とするため、期限日の範囲検索では、すでに期限を過ぎた項目も返されます。

関係

関係はナレッジグラフにエッジを作成し、ノート同士をつなぎます。個々のノートを超えた構造を構築する方法です。

構文

- relation_type [[Target Note Title]]

• relation_typeは、説明的な動詞または句です（慣例としてsnake_caseを使用します）。
• 二重角括弧[[...]]で、タイトルまたはパーマリンクによって対象ノートを指定します。
• 関係には方向があります：このノート → 対象ノート

関係の種類

種類	用途	例
implements	あるものが別のものを実装する	- implements [[Auth Spec]]
requires	依存関係	- requires [[Database Setup]]
relates_to	一般的な関連	- relates_to [[Performance Notes]]
part_of	階層／構成	- part_of [[Backend Architecture]]
extends	拡張または詳細化	- extends [[Base Config]]
pairs_with	連携して動作するもの	- pairs_with [[Frontend Client]]
inspired_by	参考資料	- inspired_by [[CRDT Research Paper]]
replaces	別のノートに取って代わる	- replaces [[Old Auth Design]]
depends_on	実行時／ビルド時の依存関係	- depends_on [[MCP SDK]]
contrasts_with	代替アプローチ	- contrasts_with [[GraphQL Approach]]

インライン関係

ノート本文内のWikiリンクは、関係セクション内に限らず、グラフのエッジも作成します。

We evaluated [[GraphQL Approach]] but decided against it because
the team has more experience with REST. See [[API Specification]]
for the full contract.

これらはreferences関係を自動的に作成します。明示的で型付きの関係には関係セクションを使用し、自然な文章での参照にはインラインリンクを使用します。

関係のヒント

• 積極的にリンクしましょう。 関係によって、孤立したノートがナレッジグラフになります。迷ったらリンクを追加してください。
• まだ存在しない場合は、対象ノートを作成しましょう。 [[Future Topic]]も有効です。そのノートが作成されると、BMが解決します。
• build_contextを使ってたどりましょう。 build_context(url="memory://note-title")は関係をたどり、関連する知識を集めます。
• カスタムの関係タイプも使用できます。 taught_by、blocks、tested_inなど、説明的なものなら何でも使用できます。

メモリURL

すべてのノートには、パーマリンクから生成されるmemory:// URLでアクセスできます。これらのURLを使って、プログラムからナレッジグラフをたどります。

URLパターン

memory://api-design-decisions          # by permalink (title → kebab-case)
memory://docs/authentication           # by file path
memory://docs/authentication.md        # with extension (also works)
memory://auth*                         # wildcard prefix
memory://docs/*                        # wildcard suffix
memory://project/*/requirements        # path wildcards

プロジェクトスコープ付きURL

複数プロジェクトの環境では、プロジェクト名を先頭に付けます。

memory://main/specs/api-design         # "main" project, "specs/api-design" path
memory://research/papers/crdt          # "research" project

最初のパスセグメントは、既知のプロジェクト名と照合されます。一致した場合は、その名前がプロジェクトスコープとして使用されます。一致しない場合、URLはデフォルトのプロジェクト内で解決されます。

メモリURLの使用

メモリURLはbuild_contextと連携し、関係をたどって関連する知識をまとめます。

# Get a note and its connected context
build_context(url="memory://api-design-decisions")

# Wildcard — gather all docs
build_context(url="memory://docs/*")

# Direct read by permalink
read_note(identifier="memory://api-design-decisions")

ノートを作成する前に

新しいノートを作成する前に、必ずBasic Memoryを検索してください。重複があるとナレッジグラフが分断されます。2つ目のノートを作成するより、既存のノートを更新するほうがほとんどの場合に適しています。

複数のバリエーションで検索する

1 回の検索では見つからないことがよくあります。正式名称、略称、頭字語、キーワードを試してください。

# Searching for an entity that might already exist
search_notes(query="Kubernetes Migration")
search_notes(query="k8s migration")
search_notes(query="container migration")

人物の場合は、フルネームと姓を試してください。組織の場合は、正式名称と一般的な略称を試してください。

判断ツリー

• エンティティが存在する → edit_note で更新します（所見を追記し、関連を追加し、古い情報を検索して置換します）
• エンティティが存在しない → write_note で作成します
• 同じエンティティかどうか不明 → まず既存のノートを読み、その後で判断します

edit_note で細かく更新する

ノートがすでに存在する場合は、ファイル全体を書き直すのではなく、対象を絞って編集します。

# Add a new observation under the existing Observations heading
edit_note(
  identifier="API Design Decisions",
  operation="insert_after_section",
  section="Observations",
  content="- [decision] Switched to OpenAPI 3.1 for spec generation #api"
)

# Fix outdated information
edit_note(
  identifier="API Design Decisions",
  operation="find_replace",
  find_text="- [status] draft",
  content="- [status] approved"
)

# Add a new relation
edit_note(
  identifier="API Design Decisions",
  operation="insert_after_section",
  section="Relations",
  content="- depends_on [[Rate Limiter]]"
)

これにより、既存の内容が保たれ、編集履歴も整理された状態になります。

ツールでノートを書く

ノートを作成する

write_note(
  title="API Design Decisions",
  directory="architecture",
  tags=["api", "architecture"],
  content="""# API Design Decisions

The API team evaluated REST and GraphQL during Q1 planning. After prototyping
both approaches, we chose REST for the public API — broader ecosystem support,
simpler caching with HTTP semantics, and a lower learning curve for external
consumers. GraphQL remains an option for internal services where query
flexibility matters more.

## Observations
- [decision] Use REST for public API #api
- [requirement] Support API versioning from v1

## Relations
- implements [[API Specification]]
- relates_to [[Backend Architecture]]"""
)

Basic Memory は、パラメーターからフロントマター（パーマリンクとメモリー URL を含む）を自動生成します。このノートには architecture/api-design-decisions というパーマリンクが設定され、memory://architecture/api-design-decisions からアクセスできます。

既存のノートを編集する

edit_note を使ってノートをその場で更新します。6 つの操作があります：append、prepend、 find_replace、replace_section、insert_before_section、insert_after_section。

# insert_after_section / insert_before_section — add lines at an existing heading
edit_note(
  identifier="API Design Decisions",
  operation="insert_after_section",
  section="Observations",
  content="- [decision] Use OpenAPI 3.1 for spec generation #api"
)

# append / prepend — add to the end of the note or the start of the body
# (use for time-ordered logs; neither one targets a section)
edit_note(
  identifier="API Design Decisions",
  operation="prepend",
  content="> Updated 2026-05-28: auth approach finalized.\n"
)

# replace_section — rewrite a named section (use for living content that stays current)
edit_note(
  identifier="API Design Decisions",
  operation="replace_section",
  section="Summary",
  content="Concise, current summary of the decision and its rationale."
)

# find_replace — swap specific text
edit_note(
  identifier="API Design Decisions",
  operation="find_replace",
  find_text="OpenAPI 3.0",
  content="OpenAPI 3.1"
)

編集によって内容が破壊的に変更される場合（replace_section、find_replace）は、まずノートを読み、そのチェックサムを渡してください。これにより、読み取ったリビジョンに対してのみ編集が適用されます。

note = read_note(identifier="API Design Decisions", output_format="json")
edit_note(
  identifier="API Design Decisions",
  operation="replace_section",
  section="Summary",
  content="Concise, current summary of the decision and its rationale.",
  expected_checksum=note["checksum"]
)

チェックサムの競合は、読み取り後に誰かがノートを変更したことを意味します。もう一度読み、新しいテキストに対して編集をやり直してください。write_note(overwrite=True) でも同様に expected_checksum を指定できます。

ノートを移動する

move_note を使って、ノートを別のディレクトリに整理します。

move_note(
  identifier="API Design Decisions",
  destination_path="archive/api-design-decisions.md"
)

デフォルトでは、移動後もパーマリンクは変わらないため、リンクは引き続き有効です。update_permalinks_on_move が有効なプロジェクトでは、新しいパスに基づいてパーマリンクが書き換えられます。

ベストプラクティス

1. まず背景を説明します。 所見を列挙する前に、このノートが存在する理由を説明してください。未来の自分（または AI の協力者）が感謝するでしょう。

2. 情報を十分に盛り込みます。 内容が豊富で、実質的なノートを書いてください。Basic Memory の検索ではノート本文から関連するチャンクが取得されるため、背景情報の多い長めのノートのほうが、見つけやすくなります。本文では、背景、理由、ニュアンスを含めて全体像を文章で説明してください。そのうえで、重要な事実を [category] content 形式の所見にまとめ、構造化クエリに対応させます。どちらも重要です。文章は意味を伝え、所見は精度を高めます。

3. 段階的に構築します。 重複を作成するのではなく、既存のノートに情報を追加してください。新しい情報を得たら、edit_note を使って所見や関連を追記します。

4. タイトルの表記を統一します。 ノートのタイトルは、ナレッジグラフにおける識別子です。API Design Decisions と Api Design decisions は異なるエンティティです。表記ルールを決めて、一貫して使ってください。

5. 関連する概念をリンクします。 ナレッジグラフの価値は、つながりによって高まります。関連が 1 つもないノートは孤立しています。役には立ちますが、つながりのあるノートほど強力ではありません。

6. グラフは自然に成長させます。 最初から完璧な分類体系を設計しようとしないでください。作業しながらノートを書き、つながりが見つかったら関連を追加し、定期的に memory-reflect または memory-defrag スキルを使って整理統合してください。