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 は本文の # 見出し と一致させる必要があります
• タグは検索可能で、情報の発見に役立ちます
• カスタムの type 値（Task、Meeting、Person など）はスキーマシステムで機能します。スキーマの定義、メモの検証、ドリフトの検出については、memory-schema スキルを参照してください。
• permalink は title と directory から自動生成されます。たとえば、ディレクトリ「specs」にあるタイトル「API Design Decisions」の場合、パーマリンクは specs/api-design-decisions、メモリ URL は memory://specs/api-design-decisions になります。ディレクトリが指定されていない場合、パーマリンクはケバブケースに変換したタイトルのみになります。パーマリンクはファイルの移動後も変わりません。手動で設定する必要はほとんどありません。

注： write_note を使用する場合、フロントマターを自分で記述する必要はありません。title、tags、note_type、metadata は個別のパラメーターです。Basic Memory がフロントマターを自動生成します。content パラメーターには、# 見出し から始まる 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つ。 複数のアイデアを1行に詰め込まないでください。
• 具体的に記述する。 [decision] Use JWT よりも、[decision] Use JWT with 15-minute expiry for API auth の方が役立ちます。
• 複数のテーマにまたがる内容にはタグを使う。 [risk] Rate limiting needed #api #security とすれば、どちらのテーマからも見つけられます。
• カテゴリはクエリで検索できます。 search_notes("[decision]") を実行すると、ナレッジベース全体からすべての決定事項を検索できます。

関連

関連はナレッジグラフにエッジを作成し、メモ同士を結び付けます。個々のメモを超えて構造を構築するための仕組みです。

構文

- 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 リンクは、Relations セクション内に限らず、グラフのエッジも作成します。

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

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

関係に関するヒント

• 積極的にリンクしましょう。 関係によって、孤立したノートがナレッジグラフになります。迷ったらリンクを追加しましょう。
• まだ存在しない場合は、リンク先のノートを作成しましょう。 [[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 による細かな更新

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

# Append a new observation to an existing note
edit_note(
  identifier="API Design Decisions",
  operation="append",
  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="append",
  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 を使うと、ノートへの追記、先頭への挿入、検索と置換ができます。

# Append new observations
edit_note(
  identifier="API Design Decisions",
  operation="append",
  section="Observations",
  content="- [decision] Use OpenAPI 3.1 for spec generation #api"
)

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

ノートの移動

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

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

移動後もパーマリンクは変わらないため、すべての [[wiki-links]] と memory:// URL は引き続き解決されます。

ベストプラクティス

1. 背景から始めます。 観察事項を列挙する前に、このメモが存在する理由を説明します。未来の自分（またはAIの協力者）が感謝してくれるでしょう。

2. 網羅性を重視します。 内容が豊富で実質的なメモを書きます。Basic Memoryの検索ではメモ本文から関連するチャンクが取得されるため、背景情報が多く含まれた長いメモほど、見つけやすくなります。本文の文章で、背景や理由、細かなニュアンスも含めて全体像を伝えます。そのうえで、重要な事実を [category] content 形式の観察事項にまとめ、構造化クエリに対応させます。どちらも重要です。文章は意味を伝え、観察事項は情報を正確に示します。

3. 少しずつ積み重ねます。 メモを重複して作成するのではなく、既存のメモに内容を追加します。学んだことに応じて、新しい観察事項や関連情報を追記するには edit_note を使います。

4. AIが生成した内容を確認します。 AIがメモを作成した場合は、正確さを確認します。AIは構造をうまく捉えますが、細かなニュアンスを見落とすことがあります。

5. タイトルに一貫性を持たせます。 メモのタイトルはナレッジグラフ内の識別子です。API Design Decisions と Api Design decisions は別のエンティティです。表記の規則を決めて、それに従います。

6. 関連する概念をリンクします。 ナレッジグラフの価値は、つながりが増えるほど高まります。関連がゼロのメモは孤島のようなもので、役には立ちますが、つながりのあるメモほど強力ではありません。

7. グラフは自然に成長させます。 最初から完璧な分類体系を設計しようとしないでください。作業しながらメモを書き、つながりが見つかったら関連情報を追加し、定期的に /reflect または /defrag を使って整理します。