storage-basicmemory

基本原則： すべてのプロジェクト成果物は、明示的なリンクとステータス追跡を行い、複数のプロジェクトが並行して進行しても信頼できる唯一の情報源を維持できるよう、[ProjectId] のもとで basicmemory に保存する必要があります。

メモ

作業を始める前に、取り組むプロジェクトの正しい [ProjectId] を特定していることを確認してください。

要件：

• basicmemory MCP ツールを使用して、[Project Artifacts] を読み書きします。
• [Project Artifacts] の種類を認識します：[Spec]、[Research]、[Descision]、[Epic]、[Story]、[Task]、[Retrospective]。
• [Project Artifacts] は、正しいプロジェクトコンテキストのもと、[ProjectId] を使用して basicmemory に保存します。

[Project Artifacts] の保存領域を操作する方法

重要： すべての [Project Artifacts] は basicmemory MCP ツールを介して操作します。 禁止事項： ファイルシステムを直接操作して [Project Artifacts] にアクセスすることは禁止されています。整理が乱れ、データが失われる原因になります。

• basicmemory_read_note - Markdown ノートを読み取る
• basicmemory_read_content - パスを指定してファイルの生のコンテンツを読み取る
• basicmemory_view_note - 書式設定されたノートを表示する
• basicmemory_write_note - Markdown ノートを作成／更新する
• basicmemory_edit_note - 操作を指定して既存のノートを編集する
• basicmemory_move_note - ノートを新しい場所に移動する
• basicmemory_delete_note - タイトルを指定してノートを削除する
• basicmemory_canvas - Obsidian キャンバスファイルを作成する
• basicmemory_search_notes - ナレッジベース全体を検索する
• basicmemory_search - ナレッジベース全体のコンテンツを検索する
• basicmemory_fetch - 検索結果の全内容を取得する
• basicmemory_recent_activity - 最近のアクティビティを取得する
• basicmemory_build_context - メモリ URI からコンテキストを構築する
• basicmemory_list_memory_projects - 利用可能なすべてのプロジェクトを一覧表示する
• basicmemory_create_memory_project - 新しいプロジェクトを作成する
• basicmemory_delete_project - プロジェクトを削除する
• basicmemory_list_directory - ディレクトリの内容を一覧表示する
• basicmemory_sync_status - ファイルの同期ステータスを確認する

計画成果物のフロントマター

計画成果物ではフロントマターが重要です。Markdown ファイルの先頭に YAML として記述し、Markdown のコードブロックにしてはいけません。

フロントマターについて

テンプレートの先頭には、--- で区切られた YAML フロントマターブロックがあります。

---
epic_id: 1
title: Epic Title
status: planned
priority: high
estimated_effort: 2 weeks
linked_spec:
  - type: spec
    target: 2.1.1-spec-title
---
# Rest of markdown content here

これは 実際の YAML フロントマターであり、Markdown のコードブロックではありません。成果物を作成する際は、この構造を正確に維持する必要があります。

フロントマターを維持するワークフロー

basicmemory_write_note を使用して計画成果物を作成または更新する場合： ステップ 1：テンプレートファイルを解析する

• フロントマターブロック（最初の --- と 2 番目の --- の間にあるすべての内容）を抽出します
• Markdown 本文（閉じる --- の後にあるすべての内容）を抽出します
• それぞれを分けておきます ステップ 2：basicmemory に渡すコンテンツを組み立てる basicmemory_write_note に渡すコンテンツは、次の形式である必要があります。

---
field1: value1
field2: value2
links:
  - type: epic
    target: 2.1.1-epic-title
---
# Markdown Heading
Markdown body content here...

重要な要件：

• コンテンツは必ず --- で始めます
• フロントマターブロックは必ず --- で終わります
• フロントマターと Markdown 本文の間には空行を入れます
• テンプレートにあるすべてのフロントマターフィールドを維持します
• ## Frontmatter の Markdown セクションを作成しないでください ステップ 3：basicmemory_write_note を呼び出す

basicmemory_write_note(
    title="artifact-title",
    folder="2-epics",  # or 1-prds, 3-research, etc.
    content=assembled_content,  # With frontmatter at top
    entity_type="epic",  # or spec, research, story, task, decision
    tags=extracted_tags,  # Optional, if tags are in frontmatter
    project=project_id
)

ステップ 4：あとは basicmemory が処理します basicmemory は自動的に次の処理を行います：

• YAML フロントマターを検出します（has_frontmatter() を使用）
• すべてのフロントマターフィールドを解析します
• Markdown 本文からフロントマターを削除します（remove_frontmatter() を使用）
• 最終成果物では、すべてのフィールドを YAML フロントマターとして維持します
• YAML フロントマターを含む適切な Markdown に変換します

フィールドのマッピング

テンプレートのフロントマターフィールドは、成果物の YAML フロントマターになります。

• epic_id: 1 → フロントマターの epic_id として保存
• status: planned → status として保存
• priority: high → priority として保存
• estimated_effort: 2 weeks → estimated_effort として保存
• linked_spec: [...] → フロントマターの YAML リストとして保存
• derived_from: [...] → フロントマターの YAML リストとして保存 これらは 構造化メタデータフィールドであり、Markdown コンテンツではありません。

よくある間違い：Markdown のコードブロック

❌ 誤り - Markdown のコードブロックが作成され、フロントマターが失われます：

---
title: Artifact Title
type: epic
permalink: some-path
---
# Artifact Title
## Frontmatter
\`\`\`yaml
epic_idid: 1
status: planned
\`\`\`
Rest of content...

✅ 正しい方法 - フロントマターが YAML として保持されます：

---
title: Artifact Title
type: epic
permalink: some-path
epic_id: 1
status: planned
---
# Artifact Title
Rest of content...

実装のベストプラクティス

1. フロントマターは常に慎重に解析する - テンプレートから YAML ブロックをそのまま抽出します
2. フィールドの順序を保持する - YAML のフィールド順序は読みやすさに影響します
3. YAML の構文を検証する - basicmemory に渡す前に、フロントマターが有効な YAML であることを確認します
4. すべてのテンプレートフィールドを含める - フィールドを削除せず、生成されたフィールドと統合します
5. 適切な YAML リストを使用する - フロントマターのリスト項目には JSON 配列ではなく - を使用します
6. 往復処理をテストする - 作成後、成果物に Markdown のコードブロックではなくフロントマターが含まれていることを確認します

[ProjectId] の命名規則と形式

ProjectId の規則：

• 形式：slugified-project-name（ケバブケース、小文字の英数字とハイフン）
• 元となる名前：Git リポジトリ名またはプロジェクト名から取得します
• 生成方法：./scripts/get_project_id.sh（自動的にスラッグ化します）
• 例：
  • リポジトリ：github.com/username/dotfiles → ProjectId：dotfiles
  • プロジェクト名：「ユーザー認証システム」 → ProjectId：user-authentication-system
  • 例の名前「My App v2」 → ProjectId：my-app-v2

新しいプロジェクトの作成

basicmemory に新しいプロジェクトを作成する必要がある場合は、必ず次の点を確認してください。

• [ProjectId] の命名規則に従います。
• 既存のプロジェクトを最初に一覧表示し、作成するプロジェクトがまだ存在しないことを確認します。
• プロジェクトを ~/Notes/Projects/[ProjectId] に保存します。
• 作業中のリポジトリと同じフォルダーにプロジェクトを保存しないでください。