實戰範例 009：5 分鐘初次體驗 MemPalace

背景

您剛聽說 MemPalace 這個本地優先的記憶宮殿，想用最短路徑確認它能不能跑起來。本範例不假設您已經理解 Wing、Room、Drawer 的完整架構，只帶您走完「安裝 → 初始化 → 加一筆記憶 → 搜回來」的封閉迴圈。跑完這五分鐘，您就有一個可重複實驗的本機 Palace。

全程零雲端、零 API key、零 LLM 呼叫。MemPalace 預設使用 ChromaDB 在本機做語意向量檢索，資料不離開您的機器。

情境

假設您正在學習一個新的程式庫，想把「官方文件提到的核心概念」與「您自己的理解」都存下來，之後用自然語言把它們叫回來。

目標：

在本機裝好 MemPalace CLI
為一個學習專案初始化 Palace
加入兩筆記憶（一筆引用、一筆心得）
用一句話搜尋驗證可找回

您想做什麼？

用戶：「我第一次用 MemPalace，能不能帶我跑一次最小的範例，確認它真的能存、能找？」

第 1 步：安裝 CLI

MemPalace 透過 uv 安裝（即 theme.yaml 的 installCommand）：

$ uv tool install mempalace
Installed 1 package: mempalace
Installed executable: mempalace

$ mempalace --version
mempalace v3.7.0

如果還沒有 uv，先依 uv 官方文件安裝。uv tool install 會把 mempalace 放進獨立的工具環境，不會污染您的專案相依。

第 2 步：初始化 Palace

走進您的學習專案目錄，初始化第一個 Palace：

$ cd ~/projects/learning-fastapi
$ mempalace init --wing "d:/projects/learning-fastapi"
✓ Palace initialized at .mempalace
✓ First wing: d:/projects/learning-fastapi
✓ Backend: chromadb (default)

--wing 把這個儲存庫登記為第一個 Wing（語境邊界）。MemPalace 會在當前目錄建立 .mempalace/：

.mempalace/
├── palace/
│   ├── palace.yaml        # Palace 設定
│   └── wings.yaml         # Wing 登記
├── db/                    # ChromaDB 向量索引
└── config.yaml

建議把 .mempalace/ 加進 .gitignore，除非您想把記憶隨專案一起送進版控。

第 3 步：加入第一筆記憶（Reference）

把官方文件的一句關鍵說明原文存入。用 reference 類型引用外部來源：

$ mempalace add --type reference \
  --wing "d:/projects/learning-fastapi" \
  --room "core-concepts" \
  --title "FastAPI Path Parameters 官方說明" \
  --source "https://fastapi.tiangolo.com/tutorial/path-params/" \
  --range "lines 1-60" \
  --tags "fastapi,path-params,docs"
✓ Created reference drawer: drawer-001.md

重點：reference 類型用 --source 指到官方文件、用 --range 標示引用範圍，MemPalace 會把該段網頁原文（Verbatim）抓回來儲存，絕不摘要或改寫。這是它能維持 96.6% R@5 檢索品質的前提。

第 4 步：加入第二筆記憶（Observation）

接著存您自己的理解。用 observation 類型記錄見解：

$ mempalace add --type observation \
  --wing "d:/projects/learning-fastapi" \
  --room "core-concepts" \
  --title "Path parameter 會自動型別轉換" \
  --content "FastAPI 直接讀函式簽名的型別註記，把 URL 字串自動轉成 int 或 float，不需要手動 parse。這跟 Flask 要自己處理很不一樣。" \
  --tags "fastapi,path-params,insight"
✓ Created observation drawer: drawer-002.md

現在同一個 Room (core-concepts) 裡有兩個 Drawer：一個引用官方、一個是您的心得。

第 5 步：用自然語言搜尋

用一句話測試語意搜尋，刻意不使用精確關鍵字：

$ mempalace search --query "URL 路徑的變數怎麼處理"
Wing: d:/projects/learning-fastapi
  Room: core-concepts

  [reference] FastAPI Path Parameters 官方說明
    Score: 0.918
  [observation] Path parameter 會自動型別轉換
    Score: 0.874

Results: 2
Latency: 182ms

兩筆都中。即便查詢用的是「URL 路徑的變數」，而記憶寫的是「path parameters」，語意檢索仍能對上。這就是它跟傳統全文搜尋最大的差別。

結果

五分鐘內您完成了一個可重複實驗的本機 Palace：

一個 Wing（學習專案）、一個 Room（core-concepts）、兩個 Drawer
雲端零依賴，全部資料都在 .mempalace/ 裡
語意搜尋可用，不用背精確關鍵字

下一步

用 mempalace link 把相關 Drawer 串起來，開始建立知識圖譜
多建幾個 Room 分主題存放，觀察搜尋如何跨 Room 比對
想理解 Wing、Room、Drawer 的設計理由，回頭讀 Palace 架構 lesson

指令	用途
`mempalace init`	初始化 Palace 並建立第一個 Wing
`mempalace add`	加入 reference 或 observation Drawer
`mempalace search`	語意搜尋全部 Drawer

關鍵學習點

先跑通再理解架構：init → add → search 三個指令就構成完整封閉迴圈，不必先讀完整份架構文件。
原文儲存是檢索品質的基礎：--content 一定要放原文，MemPalace 不摘要，這是高 R@5 的前提。
語意搜尋容許換詞：查詢不必命中儲存時的精確字串，能大幅降低日後找回記憶的門檻。
本機優先代表可隨時重來：.mempalace/ 刪掉重建沒有任何外部成本，鼓勵您多試不同的 Room 與 tag 組合。