實戰範例 001：專案初始化追蹤記憶

背景

您正在開始一個新的 API 網關專案，需要記錄初始化過程中的架構決策、技術選型與設計考量。透過 MemPalace，您能在未來開發中快速回顧這些決策，避免重複思考或遺失重要設計細節。

情境

專案目標：建立一個高可用、可擴展的 API 網關，支援微服務架構。

您已經完成了初始化討論與設計文件，現在想：

1. 記錄架構決策
2. 追蹤技術選型
3. 關聯相關設計考量

您想做什麼？

用戶：「能不能幫我將專案初始化過程中的架構決策記錄到 MemPalace，方便未來回顧？」

第 1 步：初始化 Palace

首先，在專案根目錄初始化 Palace：

$ mempalace init --wing "d:/Repo/api-gateway"
✓ Palace initialized at .mempalace
✓ First wing: d:/Repo/api-gateway

解釋：

• --wing 指定第一個 Wing 為當前儲存庫，方便按專案追蹤

生成的檔案結構：

.mempalace/
├── palace/
│   ├── palace.yaml
│   └── wings.yaml
├── db/                      # ChromaDB 存儲
│   └── chroma.db
└── config.yaml

第 2 步：添加架構決策 Drawers

添加 Reference Drawer：引用設計文件

專案中有一份設計文件 architecture-decision.md，記錄了微服務邊界決策：

$ mempalace add --type reference \
  --wing "d:/Repo/api-gateway" \
  --room "architecture" \
  --title "微服務邊界決策：按業務能力拆分" \
  --file "docs/architecture-decision.md" \
  --range "lines 1-50" \
  --tags "architecture,microservices,boundaries"

✓ Created reference drawer: drawer-001.md

Drawers 內容 (drawer-001.md)：

type: reference
title: "微服務邊界決策：按業務能力拆分"
file: "docs/architecture-decision.md"
range: ["1", "50"]
content: |
  微服務邊界應根據業務能力而非技術層次拆分。
  主要考量：
  - 團隊自主性：每個服務由獨立團隊負責
  - 部署獨立性：最小化互動需求
  - 資料一致性：避免跨服務事務

tags: ["architecture", "microservices", "boundaries"]
created_at: "2025-07-17T14:30:00Z"

添加 Observation Drawer：見解與推論

從設計討論中，您提取了一個關鍵見解：

$ mempalace add --type observation \
  --wing "d:/Repo/api-gateway" \
  --room "architecture" \
  --title "微服務邊界按業務能力拆分" \
  --content "微服務應根據業務能力而非技術層次拆分，以提高團隊的自主性與互動需求。" \
  --sources "vscode-workspace-1/session-20250717T143000.md:120-145" \
  --tags "microservices,architecture,independence"

✓ Created observation drawer: drawer-002.md

第 3 步：追蹤技術選型

添加 Reference Drawer：從官方文件引用

您決定使用 PostgreSQL 處理關聯數據，從官方文件中引用最佳實踐：

$ mempalace add --type reference \
  --wing "d:/Repo/api-gateway" \
  --room "database" \
  --title "PostgreSQL 關聯數據處理最佳實踐" \
  --source "https://www.postgresql.org/docs/current/queries-join.html" \
  --range "lines 50-150" \
  --tags "postgresql,join,performance"

✓ Created reference drawer: drawer-003.md

Drawers 內容 (drawer-003.md)：

type: reference
title: "PostgreSQL 關聯數據處理最佳實踐"
source:
  name: "PostgreSQL 官方文件"
  url: "https://www.postgresql.org/docs/current/queries-join.html"
  range: ["50", "150"]
  excerpt: |
    關聯查詢 (JOIN) 是 SQL 中處理多表同時查詢的核心運算。

    最佳實踐：
    1. 使用 INNER JOIN 是最快 的關聯類型，只返回兩表是否都匹配的行
    2. 當不在乎是否匹配時，LEFT JOIN 比 RIGHT JOIN 更直觀
    3. 避免在 ON 條件中使用 OR，會大幅降低效能

tags: ["postgresql", "join", "performance"]
created_at: "2025-07-17T14:45:00Z"

添加 Observation Drawer：技術選型的見解

您也記錄了選擇 PostgreSQL 的原因：

$ mempalace add --type observation \
  --wing "d:/Repo/api-gateway" \
  --room "database" \
  --title "選用 PostgreSQL 處理關聯數據" \
  --content "根據壓力測試，PostgreSQL 在處理複雜關聯查詢時比 MySQL 快 25%。特別是在多表 JOIN（4 表以上）時效能優勢明顯。" \
  --sources "benchmark-report.md:45-89" \
  --tags "database,postgresql,performance"

✓ Created observation drawer: drawer-004.md

Drawers 內容 (drawer-004.md)：

type: observation
title: "選用 PostgreSQL 處理關聯數據"
content: |
  根據壓力測試，PostgreSQL 在處理複雜關聯查詢時比 MySQL 快 25%。
  特別是在多表 JOIN（4 表以上）時效能優勢明顯。
sources:
  - file: "benchmark-report.md"
    lines: ["45-89"]
    reason: "benchmark 數據顯示的效能差異"
tags: ["database", "postgresql", "performance"]
created_at: "2025-07-17T14:50:00Z"
links: []

第 4 步：關聯 Drawers 以增強知識圖譜

將技術選型與設計考量關聯：

$ mempalace link \
  --source "d:/Repo/api-gateway/database/drawer-004" \
  --target "d:/Repo/api-gateway/architecture/drawer-002" \
  --type "relates_to" \
  --reason "都涉及架構設計的不同面向（微服務邊界 vs 技術選型）"

✓ Created link (relates_to): drawer-004 → drawer-002

更新 drawer-004.md：

...
links:
  - id: "rel-001"
    type: "relates_to"
    target: "drawer-002"
    reason: "都涉及架構設計的不同面向（微服務邊界 vs 技術選型）"
    weight: 1.0
    created_at: "2025-07-17T14:55:00Z"

檢視關聯：

$ mempalace list-links --drawer "drawer-004"

Wing: d:/Repo/api-gateway
  Room: database

Drawer: drawer-004 (選用 PostgreSQL 處理關聯數據)

Outgoing Links:
  [relates_to] → drawer-002 (微服務邊界按業務能力拆分)
    Reason: 都涉及架構設計的不同面向（微服務邊界 vs 技術選型）
    Weight: 1.0

第 5 步：檢視當前 Palace 結構

$ mempalace list

Wing: d:/Repo/api-gateway
  Rooms: 2, Drawers: 4

  Room: architecture (2 Drawers)
    [reference] 微服務邊界決策：按業務能力拆分
    [observation] 微服務邊界按業務能力拆分

  Room: database (2 Drawers)
    [reference] PostgreSQL 關聯數據處理最佳實踐
    [observation] 選用 PostgreSQL 處理關聯數據

結果

您的 Palace 現在有 4 個 Drawers：

• 2 個架構相關 Drawers（設計文件 + 見解）
• 2 個資料庫相關 Drawers（官方文件 + 技術選型）
• 1 個連結，關聯技術選型與設計考量

未來開發時，您可以快速檢索：

$ mempalace search --query "微服務邊界"

Wing: d:/Repo/api-gateway
  Room: architecture (2 Drawers)
    [reference] 微服務邊界決策：按業務能力拆分
      File: docs/architecture-decision.md (lines 1-50)
      Score: 0.942
    [observation] 微服務邊界按業務能力拆分
      Sources: vscode-workspace-1/session-20250717T143000.md:120-145
      Score: 0.915

Results: 2 (Precision: 0.92, Recall: 0.88)
Latency: 215ms

下一步

在後續開發中，您可以：

1. 使用 mempalace add 記錄新的架構決策
2. 使用 mempalace link 關聯相關設計考量
3. 使用 mempalace search 檢索之前的設計決策

這樣，您能避免在跨會話或跨團隊開發中遺失重要資訊，並快速回顧設計考量。

相關指令