檔案庫 - 代理谷的記憶

1. 簡介

第一週詢問「誰說什麼會執行」。第二週的主題是誰決定接下來要執行的內容。第三週的主題是跑步後留下的痕跡。本週對話即將結束，問題是哪些內容會留存下來。結果顯示，內容類型決定了內容的去向。

如果發生錯誤，系統會將相關內容移至「封存」區。塔樓會記錄所有內容，而檔案管理員 Vesper 則在底層的桌子旁。夜間燈籠會熄滅，你去問問看。

她很健談，一個月後，她也很高興能與您見面。

記錄不是記憶體。

這句話就是整個實驗室的內容。這項計畫分為四個階段，每個階段都代表塔樓的一層：

rung	地板	記憶內容	什麼原因導致
1	桌子和地板	這次造訪	session.state · SqliteSessionService
2	二樓，你的抽屜	這位訪客	user: 前置字串
3	塔樓三樓	說了什麼	Vertex AI Memory Bank
4	第四層樓 (本季)	整個山谷	BigQuery

每個階梯都是因為下一個階梯有東西掉落。

您已經知道檔案管理員的五種遺忘方式，因為您在支援服務電話中都經歷過：

	她說的話	發生錯誤
~~1~~	~~Could you give me that reference again?~~	~~在單一對話中忘記~~ - 第三週修正了這個問題
~~2~~	~~I've transferred you. 請從頭開始。~~	~~the history died with the process~~ — week three fixed this too
3	歡迎！今天需要什麼協助呢？	給上個月有未結案件的人
4	請描述損壞情形。	她上次看的是燈籠
5	我們從未見過這種情況。	本季有 31 人提出要求

第三行是本週。這項作業會以三種不同方式失敗，分別是新的造訪 (第 2 章)、紙條上沒有行的句子 (第 3 章)，以及僅存在於程序中的封存 (第 4 章)，每種方式都是一個章節。第四行留給您：look()，archive/agent.py是她讀取相片上的標記。第五行是第 5 章，為選填。

你不需要第 1 到第 3 週的資料。代理是具備指令和幾項工具的模型。本週的其餘內容不言自明。

您將撰寫三行，每一行都是記憶體概念：

該行	說明
tool_context.state[CASE] = case	狀態是由程式碼寫入，而非對話
CASE = "user:case"	前置字串為生命週期
found = await ctx.search_memory(query)	召回政策 - 檔案未儲存

您已經有一行可供閱讀的內容 (寫入政策 await ctx.add_events_to_memory(...))，而第 3 章會說明該政策的作用，然後您再寫入使用該政策的程式碼。

另外兩個步驟完全不是編輯作業：您建構塔樓 (代管 Memory Bank 的 Agent Engine)，而相同的程式碼會自行連線至塔樓；您載入資料倉儲 (BigQuery)，在資料倉儲上鋪設圖表，並將兩個受控查詢 (一個依據意義，一個依據連線) 交給同一個代理程式。

每個章節都會執行相同的迴圈，而這也是您在自己的代理程式中使用的迴圈：讀取程式碼 → 撰寫程式碼行 → 在塔樓中觀看。不會先執行任何中斷的項目，也不會重新啟動任何項目，更不會有任何 Ctrl+C 項目：系統會在下一則訊息中擷取所有編輯內容，而連線至伺服器塔台的檔案中，每項要求都會重新讀取一行。高塔是重新繪製的圖案：它會讀取您編輯的相同檔案，並有三個按鈕：「🌙」結束當天、「🗓」開始下一次造訪、「🔥」忘記您。您在程式碼和終端機中執行的所有其他操作。

這兩個位置永遠不會變更工作：分頁 1 是終端機，分頁 2 是封存。工作台 (adk web) 只會在第 1 章出現一次，用於查看原始工作階段狀態，之後就不會再用到。下方每個 👉 都會說明是哪種。👉💻 是分頁 1，👉🖥 是分頁 2，👉🔬 是工作台。👉📖 是「開啟檔案並讀取」，沒有任何變更，而 👉✏️ 是編輯的步驟。如果步驟要求你對 Vesper 說些什麼，下方方塊中會顯示確切訊息，請直接複製。如果某個章節的標題結尾是「— read only」，則不需要輸入、貼上或點選任何內容：其中的程式碼已在存放區中執行，並列印供您閱讀。

Vesper 門上的句子是頂端的句子。本週的結尾句是整個賽季第四週的結尾：

事實和偏好設定應分別儲存在不同商店。

2. 🧰 設定

• 內容：指向專案或貼上金鑰、安裝，並證明工具鍊為綠色。
• 原因：這裡不會啟動任何項目。每個伺服器都會在需要該伺服器的步驟之前啟動，因此開啟畫面時，您會知道哪個指令擁有該畫面。
• 方式：一個用於建立專案的指令碼、一個用於安裝並指向 Vertex AI 的指令碼，以及一個用於讀取程式碼並告知您所在位置的預先檢查指令碼。

本實驗室的所有內容都會在 Cloud Shell 中執行，其中已安裝 Python、uv 和 gcloud，且您可以使用自己的憑證，透過 Vertex AI 存取 Gemini。本實驗室中沒有任何 API 金鑰，也不需要在筆電上安裝任何項目。

本實驗室無法提供已啟用計費功能的 Google Cloud 專案。步驟 1 會提供可支付費用的帳戶；步驟 4 則會將該帳戶轉換為專案，或選取您在第一週、第二週或第三週建立的 Agent Valley 專案。請依序執行這些步驟，因為步驟 4 之後的每個步驟都會讀取步驟 4 確定的專案。

1. 取得含帳單的帳戶 (約 1 分鐘)

🌐 請務必先完成這項操作。使用已啟用帳單功能的 Google 帳戶登入。任何這類帳戶都可以。如果沒有，請開始免費試用，這樣您就會有帳單帳戶，這也是步驟 4 的必要條件。

2 · 開啟 Cloud Shell (約 1 分鐘)

🌐 點選 Google Cloud 控制台頂端的「啟用 Cloud Shell」，也就是標題中的終端機形狀圖示。

🌐 點選「Open Editor」(開啟編輯器) (含鉛筆的開啟資料夾圖示)。這時會開啟 Cloud Shell 編輯器，左側顯示檔案總管，每當步驟標示為 👉✏️ 時，您就會在這裡作業。

🌐 如果系統在今天任何時間提示您授權，請點選「授權」繼續操作。

🌐 在編輯器中開啟終端機，也就是分頁 1，除非另有說明，否則每個 👉💻 步驟都會在此執行。「分頁 2」是「封存」，您會在第 1 章中開啟這個分頁，就在需要這個分頁的步驟之前。如果終端機尚未顯示在畫面底部，請依序點選「View」→「Terminal」開啟：

🌐 確認目前登入的帳戶，應該是步驟 1 中的帳戶：

gcloud auth list

開啟檔案的方式有兩種。每個 👉✏️ 步驟都會命名檔案，例如 archive/agent.py。左側的檔案總管會帶您前往該處 (agent-valley-archive → archive → agent.py)，或在終端機中輸入 cloudshell edit ~/agent-valley-archive/archive/agent.py，檔案就會在上方編輯器中開啟。請使用您偏好的方式；實驗室會命名路徑，因為這樣可以清楚指出所指的哪個檔案。

您輸入哪些方塊？標示 bash 的區塊是終端機的指令，一律以 cd 開頭，因此您可以將其貼到任何分頁中。標示 console 的區塊不是您輸入的內容，而是預期會看到的輸出內容。沒有語言的區塊一律可供複製：在 👉🖥 或 👉🔬 下方是 Vesper 的訊息，在 👉✏️ 下方則是可貼到檔案中的程式碼片段。

唯讀。如果章節標題結尾為「— 唯讀」，則無法輸入、貼上或點選任何內容。其中的 python 和 sql 是已在存放區中且正在執行的程式碼 (或在第 5 章中，已在指令碼中執行)，並會列印出來，方便您瞭解其用途。這類章節的開頭都會附上相關附註。

3. 取得實驗室 (約 1 分鐘)

💻 複製存放區 - 這是封存存放區，不是第一週、第二週或第三週的存放區：

cd ~
git clone https://github.com/cuppibla/agent-valley-archive
cd agent-valley-archive

4. 建立專案，或重複使用前幾週的專案 (約 2 分鐘)

💻 一個指令碼會找出您的帳單帳戶、在該帳戶中建立專案，並將 Cloud Shell 指向該專案。如果您已完成第一週、第二週或第三週的課程，系統會先找出 Agent Valley 專案，並提供重複使用該專案的選項。請選取「是」，這樣就不必考慮第二個計費專案：

cd ~/agent-valley-archive
./setup_project.sh

👀 預期會看到所選帳單帳戶的 ✓、所建立或重複使用的專案 ✓，以及類似以下的結尾：

cd ~/agent-valley-archive
Project ready: agent-valley-4271
  Next:  ./setup_codelab.sh

agent-valley-4271 是您的專案 ID，您的專案 ID 會有不同的數字。當中會發生四件事：

帳單	如果有的話，系統會採用最新的 [YYYY-MM-DD] GDP Credit: 帳戶，否則會採用任何其他已開啟的帳單帳戶
project	尋找您已擁有的 Agent Valley 專案 (第一週、第二週或第三週)，並提供重複使用該專案的選項；否則會建立 agent-valley-XXXX，並將該帳單帳戶連結至專案
選取	會將 ID 寫入 ~/project_id.txt 並執行 gcloud config set project，因此之後不會要求您輸入 ID
等待時間	輪詢，直到專案實際獲准放送為止，最多兩分鐘

🌐 控制台中現在有相同的專案，其 ID 位於資訊主頁的「Project info」(專案資訊) 資訊卡中：

為什麼最後會停在原地等待？幾秒前建立的 Google Cloud 專案還無法提供服務：IAM 政策仍在傳播，且呼叫會傳回 403 IAM_PERMISSION_DENIED。這是最有可能出錯的設定，而且不是帳單或權限問題，因為上述幾行程式碼已證明專案存在，且已連結帳單。指令碼會吸收此處的等待時間，因此步驟 5 中的即時模型呼叫不會進入該時間。如果專案是從前幾週重複使用，則完全不需要等待，因為專案已允許放送數週。

可安全重新執行。如果發生任何問題，只要再次執行 ./setup_project.sh 即可。系統會先讀取 ~/project_id.txt，只要該專案仍存在，就會重新啟動專案，並連結帳單 (如果這是未完成的部分)，因此第二次執行不會默默建立第二個專案。

No open billing account? 指令碼會停止執行，不會變更任何其他項目，並列印後續步驟。在十次中，有九次 Cloud Shell 登入的帳戶與有月結單的帳戶不同，請比較 gcloud auth list 與步驟 1。

Could not create a project？部分帳戶 (尤其是公司帳戶) 無法建立專案，且每個帳戶都有專案配額。指令碼會列印控制台指令，供您手動建立專案。建立完成後，請將 ID 放入 ~/project_id.txt 並重新執行 ./setup_project.sh，指令碼就會改用該專案。

5 · 安裝並指向 Vertex AI (~3 分鐘)

💻 安裝 uv、匯出將 ADK 傳送至 Vertex AI 的三個變數，然後執行設定：

cd ~/agent-valley-archive
curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.local/bin/env
export GOOGLE_GENAI_USE_VERTEXAI=TRUE
export GOOGLE_CLOUD_PROJECT=$(gcloud config get project)
export GOOGLE_CLOUD_LOCATION=global
./setup_codelab.sh

$(gcloud config get project) 有要傳回的內容，因為步驟 4 已設定。這也是步驟 4 先執行的原因。

為什麼是 global，而不是區域？Vertex 上的 Gemini 會透過動態共用配額提供這個實驗室，因此沒有佈建的輸送量，繁忙的區域可能會在您沒有任何錯誤的情況下回答 429 RESOURCE_EXHAUSTED。global 會運用各區域的容量，而非單一區域。第 4 章的塔樓是例外情況：Memory Bank 是區域性的，因此會取得自己的 MEMORY_BANK_LOCATION=us-central1，而生成流量則會留在 global。

setup_codelab.sh 具有等冪性，可安全地重複執行任意次數。這項功能會依序執行下列五項操作：

api	讀取專案步驟 4 選取內容，並在該專案上啟用 aiplatform.googleapis.com (Vertex AI 和代管 Memory Bank 的 Agent Engine) 和 bigquery.googleapis.com (第 5 章的倉庫)
uv env	uv venv 會建立 .venv (或重複使用現有的)，然後 uv sync 會安裝 uv.lock 釘選的項目，包括 google-adk、google-genai 和其下所有項目
基地	在 site/ 中執行 npm ci，因為封存檔本身就是 Next.js 應用程式，所以第 1 章的 bash valley.sh 無須下載任何內容；如果套件已存在，則會略過
.env	寫入實驗室讀取的變數 (GOOGLE_GENAI_USE_VERTEXAI、GOOGLE_CLOUD_PROJECT、GOOGLE_CLOUD_LOCATION、MEMORY_BANK_LOCATION 和 BQ_DATASET)，且任何位置都沒有 API 金鑰
模型檢查	會對 Gemini 進行一次實際呼叫，因此不良專案會在設定時失敗，而不是在章節內稍後失敗

為什麼在您剛匯出這些變數時，.env 會有影響？因為 ADK 會載入.env 殼層匯出項目，因此該檔案會勝出。setup_codelab.sh 會為您撰寫 global，但 .env 才是實際決定要連線至哪個端點的項目。第 4 章會在同一個檔案 AGENT_ENGINE 中新增一行，並為您寫入，而且 Archive 會在每次要求時重新讀取檔案，因此該行會生效，不必重新啟動任何項目。

只要有 API 金鑰，就能開始使用。第 1 到 3 章也使用 AI Studio 金鑰執行。.env第 4 章會建構高塔 (Vertex AI Memory Bank)，第 5 章的倉庫則是 BigQuery。這些是 Google Cloud 服務，因此第 4 章和第 5 章需要啟用計費功能的專案，而這正是您在步驟 4 中建立的專案。

6 · 證明是綠色 (約 1 分鐘)

💻 執行預檢 - 每個勾號都是實際探測，而非猜測：

cd ~/agent-valley-archive
uv run python scripts/preflight.py

👀 預檢會向模型提出一個問題，驗證您的憑證是否有效，檢查封存檔的套件是否就位，然後讀取您的程式碼並列印本週進度列：

cd ~/agent-valley-archive
  desk      ▢ the slip      · write_down writes nothing         chapter 1 · EDIT ONE
  floor 1   ✓ the file      · SqliteSessionService              chapter 1, read only
  floor 2   ▢ the drawer    · CASE = "case"                     chapter 2 · EDIT TWO
  floor 3   ✓ what was said · closing time files the day        chapter 3, read only
  floor 3   ▢ the asking    · recall never looks                chapter 3 · EDIT THREE
  floor 3   ▢ the tower     · InMemoryMemoryService             chapter 4 · built, not edited
  floor 3   ✓ the rules     · USER_PREFERENCES, LANTERN_CONTEXT chapter 4, read only

其中三項已勾選。這些是您只會閱讀的內容。三行是您撰寫的內容，一行是您建構的塔。您隨時可以在實驗室中再次執行預檢，系統會讀取檔案而非檢查清單，因此可顯示您目前的位置。

3. Session、State、SqliteSessionService

• 什麼 - 寫一行；啟動工作台一次，然後觀察滑動填入；然後在塔中也是如此；然後閱讀它為何能存活一晚。
• 原因：首先，記憶體不會自行記憶任何內容。有人會寫出這種東西。
• 如何 - agent.py 中的一行，然後不變更任何其他內容。

編輯一

👉📖 開啟 archive/agent.py 並找到 write_down。請閱讀以下內容：

    case = dict(tool_context.state.get(CASE, {}))
    if case.get(field):
        return {"already_written": {field: case[field]}}
    case[field] = value
    # 👉 EDIT ONE — chapter 1. She heard you. Nothing was written. Delete the
    #    "# " in front of the next line, then save — the slip is session state,
    #    and state is written by code, never by the conversation:
    # tool_context.state[CASE] = case
    return {"written": {field: value}}

函式會在本機 dict 中建構單據，然後傳回該單據，而本機 dict 會隨著呼叫而終止。照原樣執行這項操作，Vesper 就能完美地聽到你的聲音：四個 write_down 呼叫會觸發，每個呼叫都會回應 "written"，且工作階段狀態會保持空白，因為沒有任何內容傳送至該狀態。她聽到你的心聲了。未寫入任何內容。

👉✏️ 仍在 archive/agent.py 內，在 write_down 中：刪除一行前面的 #，也就是 # 和後方的空格。變更前：

    case[field] = value
    # 👉 EDIT ONE — chapter 1. She heard you. Nothing was written. Delete the
    #    "# " in front of the next line, then save — the slip is session state,
    #    and state is written by code, never by the conversation:
    # tool_context.state[CASE] = case
    return {"written": {field: value}}

變更後：

    case[field] = value
    # 👉 EDIT ONE — chapter 1. She heard you. Nothing was written. Delete the
    #    "# " in front of the next line, then save — the slip is session state,
    #    and state is written by code, never by the conversation:
    tool_context.state[CASE] = case
    return {"written": {field: value}}

。

紙條會填入

👉💻 啟動工作台。這是您在實驗室中唯一一次開啟這個視窗，也是唯一會以原始 JSON 格式顯示工作階段狀態的視窗：

cd ~/agent-valley-archive
uv run adk web . --allow_origins="*"

--allow_origins="*"為必填欄位。Cloud Shell 的網頁預覽功能會代理您的瀏覽器，因此如果沒有這項功能，UI 會載入，但您的第一則訊息會因 403 而無法傳送。請保留結尾的 .，因為這是將 archive 放入應用程式清單的必要元素。

👉🔬 開啟工作台，然後選取「Web Preview」→「Preview on port 8000」(網頁預覽按鈕是 Cloud Shell 右上方的眼睛和視窗圖示)。選取「封存」，然後在輸入任何內容前，按一下左側面板中的「狀態」。

👀 空白。目前沒有人說話。

👉🔬 現在請在同一則訊息中說出以下內容：

Hi! My lantern keeps going out at night. My case number is k7f2, and there's a little q7 stamped on the base.

👀 四個 write_down 晶片會觸發 - 點選一個並讀取 JSON："written": {"no": "k7f2"}。現在再次點選「狀態」。

case   {"no": "k7f2", "item": "lantern", "mark": "q7",
        "symptom": "keeps going out at night"}

👀 空白，然後在同一則訊息中填滿。這就是她記得的內容，而且不會單獨顯示。您撰寫的程式碼會寫入該行。這就是整個機制：一個寫入 tool_context.state 的簡單函式，以及一項指令，告訴她每當訪客說出符合紙條上某行內容的話時，就使用該函式。

👉🔬 問她：

What's my case number?

👀 k7f2. 她照著紙條唸出內容，如果沒有 EDIT ONE，她會要求你提供支援清單中的第一行，也就是某個對話中的一行。

這兩道防線是紙本表單：四條短線，每條線各寫一次。這些指標比您想像的更重要。如果沒有這些限制，模型會發現可以將整段對話倒入 symptom，而第 3 章 (整章的重點是單據上沒有該項的欄位) 會悄悄停止成立。商店形狀是由撰寫商店形狀的程式碼強制執行，或不強制執行。

一行，沒有示範。程式碼不一定能存取對話內容。這張紙條上印有兌換代碼，請先記住這個想法，本實驗室從未爭論過，只是持續保持真實。

為什麼提示是在程式碼中建構。開啟下方的 house()。ADK 會直接從工作階段狀態中，以純字串指令取代 {case}，但第 2 章會變更該鍵的 name，因此也必須編輯文字中的 {case}。一處編輯，一處顯示。

現在前往高塔

👉💻 工作台已完成，您可以讓工作台繼續執行，或關閉工作台的分頁；實驗室的其餘部分位於「封存」中。開啟第二個終端機分頁 (分頁 2 - Archive)：

cd ~/agent-valley-archive
bash valley.sh

sh: line 1: next: command not found？「Archive」是 Next.js 應用程式，這行程式碼表示其套件不完整，通常是第一次npm install中斷，導致 site/node_modules 資料夾中沒有 next。再次執行 bash valley.sh：這個指令會尋找 next 二進位檔 (而非資料夾)，並在缺少該檔案時重新安裝。如要手動操作，請依序輕觸 cd ~/agent-valley-archive/site && npm ci 和 bash valley.sh。

👉🖥 依序點選「網頁預覽」→「變更通訊埠」開啟封存檔，輸入 3440，然後點選「變更並預覽」。3440 不在 Web Preview 的快速清單中 (預設為 8080)，因此您必須手動設定一次。依序按下「開始」▶ 和「封存」。你已抵達門口。選擇來訪者 (姓名和物種)，然後進入。

👀 一棟建築物。Vesper 位於一樓的辦公桌，你可以在這裡與他對話。她上方有第一層、第二層、第三層和黑暗的閣樓。四個階梯代表四層樓。你的寵物會坐在底層，因為你只爬了這麼高。圖旁邊的欄位會列出各樓層目前有哪些商店，與簡介中的表格相同，順序也一樣。右側沒有任何按鈕。

👉🖥 將這四項內容貼到對話下方的方塊中 (必須是這則訊息)，然後按下 Enter 鍵：

Hi! My lantern keeps going out at night. My case number is k7f2, and there's a little q7 stamped on the base.

👀 看著書桌。系統會逐行在繪圖上和旁邊的「紙條」下方寫入紙條內容。工具和狀態都相同：高塔只是繪製 write_down 寫入的內容，而且在實驗室的其餘部分也會繼續這麼做。

她記得一整晚 - 僅供閱讀

唯讀。您只需要查看一行，不必變更任何內容：造訪記錄位於檔案中，而非程序中。

👉📖 開啟 archive/service.py 並讀取一行內容：

DB = str(Path(__file__).resolve().parents[1] / "archive.db")
_sessions = SqliteSessionService(DB)

你輸入的內容和實際內容

該行	說明	儲存位置
tool_context.state[CASE] = case	工作階段狀態：由程式碼寫入，由指令讀取	桌面 · session.state
SqliteSessionService(DB) - 你只讀取該檔案	工作階段儲存區：檔案中的造訪記錄，而非程序	一樓 · archive.db

這個鈴聲會響一次，而且在關門時間後仍會響。下次造訪時不會保留。

4. 使用者狀態

• 什麼 - 一個月後再回來，收據就不見了。五個角色，而且會跟著你。
• 為什麼：工作階段就是一次造訪。下一次造訪是新的工作階段，且從未見過上一個工作階段。
• 「How」一共有五個字元，因此 state.py 的長度為 5。

👉🖥 按下 🗓 一個月後。這是同一位訪客的新工作階段，就像第 3 週的「發起新對話」一樣。

歡迎來到封存內容頁面。你今天想做什麼呢？

👉🖥 看著塔樓。一樓還有另一本書，這次是《The Great Gatsby》。二樓的抽屜是空的。桌上的紙條是空白的。

👀 原因：系統會將收據寫入工作階段狀態，而工作階段就是這次造訪。變更造訪次數、變更工作階段。由於未提供任何資訊，因此沒有任何內容轉移。最後一次的造訪記錄仍保留在檔案中 (也就是一樓的第一本書)，但收據是根據一次性造訪的金鑰所寫。

編輯 2

👉✏️ 開啟 archive/state.py。找出 👉。變更前：

# 👉 EDIT TWO — chapter 2. Five characters. A key with no prefix lives for one
#    visit; `user:` follows the visitor into every visit after this.
CASE = "case"

變更後：

CASE = "user:case"

。不重新啟動：Archive 會在每則訊息中重新匯入程式碼。

👉🖥 再次貼上相同的四個項目，也就是這段訊息：

Hi! My lantern keeps going out at night. My case number is k7f2, and there's a little q7 stamped on the base.

👉🖥 接著再次按下一個月後的按鈕 (與先前相同)。

👀 二樓的抽屜上寫著你的名字，裡面有四個欄位。桌上的紙條還是那四行字，你走進來時，紙條就從抽屜裡拿出來了。你的寵物已升上一層樓。每次造訪時都使用相同金鑰，且只有一個值：這就是前置字串的用途。

前置字串為生命週期。

前置字串	存活時間	哪個樓層
(無)	這次造訪	辦公桌
user:	該訪客的每次造訪	二樓，你的抽屜
app:	所有人，永久	四樓部分區域
temp:	這回合就好，甚至不用爬樓梯	—

一張桌子，四個抽屜。本章將介紹其中一項。

她現在認識你

👉🖥 這是全新的通話，你尚未說過任何話。問她：

What did I bring in last time?

👀 我記下你帶進來的是燈籠，案件編號為 k7f2。該裝置標示為 q7，你提到裝置會在夜間持續關機。這段文字的每個字都是從抽屜中取出，而非來自對話。這次造訪只有一則訊息，且該訊息未命名。這就是使用者層級狀態的用途：訪客說話前，系統就會在每次造訪時提供 user: 金鑰。

抽屜只能容納紙條上的四行文字，你說的任何話 (你嘗試了什麼、你為什麼在意、你是否想要新的) 都沒有記錄，一個月後就會消失。導覽匣跨越月份。但句子不會。第 3 章會說明這項功能。

你輸入的內容和實際內容

該行	說明	儲存位置
CASE = "user:case"	前置字元是生命週期，也就是與訪客範圍相同的金鑰，而非與造訪範圍相同	二樓 · user: 州

這個階段觸及一位訪客。抽屜會跟著你移動，但對話不會。

5. InMemoryMemoryService

• 什麼：讀取檔案當天的行，寫入詢問的行；然後是結束時間和一個問題。
• 為什麼：這張紙條是表單。表單會顯示您提供的行。人們不會逐行說話，而記錄他們說的內容只是記憶的一半。
• 如何：朗讀 file；一行 recall；然後一個 🌙、一個 🗓、一個問題。

她回家的路程 (僅供參考)

唯讀。這是寫入政策，也就是本章讀取且永不變更的那一行。您在本章編寫的程式碼行是讀取作業，請繼續往下看。

👉📖 開啟 archive/agent.py 並找到 file。這是當天結束時執行的節點，也就是按下「今天就到這裡吧」🌙 時：

async def file(ctx: Context, node_input: Any):
    t0 = time.monotonic()
    n = len(ctx.session.events)

    await ctx.add_events_to_memory(events=ctx.session.events, custom_metadata=FILING)

    return closing(ctx, t0, n)       # says what got written, and how long it waited

一行。當天所有活動 (包括這次造訪的所有事件) 都會傳送至記憶體服務，並一併傳送 FILING。這就是寫入政策：保留哪些資料 (當天) 和何時保留 (結帳時間)。ADK 會提供動詞 add_events_to_memory，但不會參與決策。

系統不會記住已填寫的欄位

該行會將日期放在時間軸上。不會從中扣除任何金額。如果沒有人查看，滿滿一架卡片和空架子一樣沒用，而程式碼發布時，沒有人會查看：recall，也就是在每個問題上 Vesper 之前執行的節點，不會向塔樓詢問任何問題。無法在適當時間回憶起的儲存內容並非記憶，而是記錄。「看」是另一半，由你撰寫。

編輯三：提問

👉📖 在 archive/agent.py 中，找出 recall，也就是 file 上方的函式。這是純函式節點，會在每個問題上先執行 Vesper，而不是由模型決定何時要搜尋，因此即使找不到任何內容，也會顯示結果。請閱讀以下內容：

    if query.strip():
        try:
            # 👉 EDIT THREE — chapter 3. Filed is not remembered: the cards are on
            #    the shelf and nobody is looking at them. Delete the "# " in front
            #    of the next line, then save:
            # found = await ctx.search_memory(query)
            pass
        except ValueError:
            # no memory service wired on this runner — degrade, do not crash
            pass

👉✏️ 仍在 archive/agent.py 內，在 recall 中：刪除一行前面的 #，也就是 # 和後方的空格。變更前：

        try:
            # 👉 EDIT THREE — chapter 3. Filed is not remembered: the cards are on
            #    the shelf and nobody is looking at them. Delete the "# " in front
            #    of the next line, then save:
            # found = await ctx.search_memory(query)
            pass
        except ValueError:

變更後：

        try:
            # 👉 EDIT THREE — chapter 3. Filed is not remembered: the cards are on
            #    the shelf and nobody is looking at them. Delete the "# " in front
            #    of the next line, then save:
            found = await ctx.search_memory(query)
            pass
        except ValueError:

將 pass 留在原處，因為 found 已在上方設為 None，因此現在不會執行任何動作。

。不必重新啟動。

兩行程式碼，兩項政策，其中一項是您編寫的。寫入政策會決定要保留哪些資料，以及保留時間 (關閉時間、整天)。回想政策會決定何時要回想，以及回想的內容 (每個問題、問題本身)。ADK 會提供動詞 (add_events_to_memory、search_memory)，並排除政策。這才是正確的拆分方式，因此您有權撰寫要求。

打烊時間

👉🖥 說出紙條上沒有的內容。一則或三則訊息：

I read by it at night, so night is exactly when I need it.
I've tried hanging it higher. No change.
I don't want a new one — it was a gift.

👉🖥 然後按下 🌙 今天的內容到此結束。

👀 看著書桌。你說的三件事從滑梯上起飛，然後漂浮上去，最後降落在三樓。在列出塔樓的資訊卡下方，會顯示你傳送的每則訊息，並標示 quote，以及你逐字逐句的句子，上方則會顯示「在此過程中」。降落前，桌上的燈會一直亮著。

什麼是 FILING？檔案頂端的小型字典：{"wait_for_completion": True, ...}。她會將塔連同當天交給塔主。等待原因：簡短形式的 add_session_to_memory() 會在背景記錄當天情況，因此可能暫時不會顯示事實，就像塔樓會繪製尚未填滿的樓層。第 4 章會回到這個字典。

一個月後，她知道

👉🖥 按下 🗓 一個月後，然後詢問：

What have I already tried?

👀 你試過將攝影機掛高一點，但沒有幫助。她知道。收據上沒有這類資訊，因此櫃員無法回答這個問題；recall找到卡片後，將資訊寫入 ctx.state["recalled"]，並按照指示操作。其中一行是差異。

而這一切都是她想像出來的

查看機箱旁邊的卡片下方：在此程序中。目前記憶體是 InMemoryMemoryService，也就是 bash valley.sh 內的字典，而且與該程序存續時間完全相同。今晚關閉塔樓，明天再開啟：書本在第一層，抽屜在第二層，第三層是黑色的。案件已儲存在檔案中。你說的內容會保留在程序中，但程序已消失。

持續性並非記憶體。

第三層樓目前有兩個問題：一是正在處理中，二是您自己的話，也就是引言，而非事實。下一章會修正這兩項問題，完全不需要任何程式碼。

你讀取、撰寫的內容和內容類型

該行	說明	儲存位置
await ctx.add_events_to_memory(events, custom_metadata=FILING) - 你只讀取該檔案	寫入政策 - 一整天，在關閉時間	三樓 · 記憶體服務
found = await ctx.search_memory(query) - 編輯三	回憶政策 - 每個問題，在她回答之前	recall() → ctx.state["recalled"]

這個層級會擷取所說內容，並以您自己的話儲存在某個程序內的字典中。這兩半都是錯誤的，下一章會完全不使用程式碼，修正這兩個問題。

6. MemoryBank

• 內容：一個指令碼會建構 Memory Bank；您已有的兩行程式碼會開始將事實寫入 Memory Bank，並讀取這些事實。
• 原因：記憶體服務是服務。封存位置是部署決策，而非代理程式決策，因此您可以在不變更代理程式的情況下變更封存位置。
• 如何：執行 make_tower.py、說出三句話、按下 🌙、按下 🗓，然後提出一個問題。然後唯讀查看寫入和讀取作業。

建造高塔

第 3 章的 3 樓是 bash valley.sh 內的 Python 字典。Memory Bank 是該層樓的管理版本：它位於專案的 Agent Engine 執行個體中，會保留從當天提煉出的事實，而非句子，並根據意義而非共用字詞尋找事實。您不必將 Vesper 部署至 Agent Engine 即可使用，即使執行個體未部署任何內容，仍會代管 Memory Bank，而這正是指令碼建構的內容：無人居住的塔樓，唯一的工作是保管卡片。

👉💻 在分頁 1 (約 1 分鐘)：

cd ~/agent-valley-archive
uv run python scripts/make_tower.py

👀 預期：

  building the tower in YOUR_PROJECT / us-central1 — about a minute...
  built, with the two topics in archive/topics.py configured on it.

  resource: projects/.../locations/us-central1/reasoningEngines/6792...
  AGENT_ENGINE written to .env

  Next — nothing to restart. The Archive reads .env on every message:
    look at floor three — under the cards it now says Memory Bank.
    (adk web, if you use it:  --memory_service_uri "agentengine://projects/.../reasoningEngines/6792...")

一次 SDK 呼叫 (agent_engines.create()) 和一行寫入 .env 的內容。Archive 會在每次要求時重新讀取該檔案，因此不需要重新啟動。

如果指令碼拒絕。Memory Bank 是 Vertex AI 服務，因此需要啟用計費功能的 Google Cloud 雲端專案，並啟用 aiplatform.googleapis.com，AI Studio 金鑰無法存取。指令碼會列印缺少哪些項目。

觀看運作方式

👉🖥 查看三樓，高塔會在幾秒內自行重新繪製。「卡片」下方現在顯示「Memory Bank」，且書架是空的：第 3 章的三個引文正在處理中，但這不是處理程序。再次說出這三句話，可以一次說完，也可以分三次說：

I read by it at night, so night is exactly when I need it.
I've tried hanging it higher. No change.
I don't want a new one — it was a gift.

👉🖥 按下 🌙 今天的內容到此結束。現在關閉時間約為八秒，塔正在擷取資料。然後看看三樓。

👀 這些卡片並非你的句子。他們會說「我晚上會用燈籠看書，但燈籠會一直熄滅」和「我已經試過把燈籠掛高一點了」，每則訊息都會標示日期 fact。蒸餾。輸入的內容是對話。結果是事實。

👉🖥 一個月後🗓，再次拜訪她 (這是新的拜訪，因此對話中不會再出現您剛才說的任何內容)，並問她這個問題 (與卡片內容完全無關)：

Should I just get a different lamp?

👀 你提到這是禮物，因此不想更換燈籠，而且你已嘗試將燈籠掛高。這張卡片上的每個字都來自於她，而且只有她才能知道：這次拜訪是舊訊息。相似度搜尋。塔羅牌的意義與問題中的字詞相符，但字詞不同。問題中是「燈」和「不同」，資訊卡中則是「燈籠」和「取代」。現在已不在程序中：今晚關閉塔台，明天就會有卡片，因為卡片位於 Agent Engine，而非 bash valley.sh。

在控制台中查看。Google Cloud 控制台 → 搜尋「Agent Engine」→ agent-valley-archive-tower → Memory Bank。您可以在該處檢查從造訪內容擷取的資訊，並在任何程式碼外部稽核記憶體。

寫入和讀取 - 僅限讀取

只能閱讀內容，無法輸入任何文字。以下兩行都已在 archive/agent.py 中，且已與基地台通訊；tower_service 已在 archive/service.py 中。這個部分說明他們在搬家後的生活。

archive/agent.py 中的任何內容都不會變更。您在第 3 章中遇到的兩行程式碼，就是負責完成所有這些工作；只有背後的服務會移動。

寫入 - file，這是您在第 3 章中讀取的行：

await ctx.add_events_to_memory(events=ctx.session.events, custom_metadata=FILING)

在她的腦海中，這保留了你的句子。在 Memory Bank 中，這是 memories.generate：擷取模型會讀取日期，並在 (app_name, user_id) 下方寫入事實，這與用於為抽屜建立索引的配對相同，因此一位訪客的塔樓就是該訪客的塔樓。FILING 是她與當天一起交出的東西：

FILING: dict[str, Any] = {
    "wait_for_completion": True,
    "allowed_topics": TOPICS,
}

wait_for_completion 是八秒：擷取是模型呼叫，且只有在事實存在時，呼叫才會傳回。allowed_topics 是可能保留的內容，也就是 archive/topics.py 中的兩個主題 (USER_PREFERENCES 和 LANTERN_CONTEXT)，是在腳本建構塔樓時設定。告訴她你午餐吃了什麼，但系統不會擷取這項資訊，不是因為提示要求忽略，而是因為沒有主題可容納這項資訊。系統會在撰寫時決定不應記憶的內容，而不是在提示中。

讀取內容：recall，您在 EDIT THREE 中撰寫的行：

found = await ctx.search_memory(query)

在她的腦海中，這算是共用字詞。在 Memory Bank 中，這是 memories.retrieve，並內嵌問題：系統會傳回這個訪客範圍內最接近的事實，這就是問題中沒有任何資訊卡字詞，但仍找到正確資訊卡的原因。

他們搬遷的原因 - tower_service in archive/service.py，僅供參考：

def tower_service(engine: str) -> BaseMemoryService:
    """The memory service for a tower name — or, with none, for her head."""
    if engine:
        from google.adk.memory import VertexAiMemoryBankService

        return VertexAiMemoryBankService(
            project=os.environ["GOOGLE_CLOUD_PROJECT"],                      # which project
            location=os.environ.get("MEMORY_BANK_LOCATION", "us-central1"),   # where it lives
            agent_engine_id=engine.split("/")[-1],                           # WHICH tower
        )
    return InMemoryMemoryService()

三個參數，並會取代 InMemoryMemoryService 放入 Runner(memory_service=...)。讀取和寫入的字元數沒有變更。只有住家會移動，且住家名稱在 .env 中為一行。

在她的腦海中 (第 3 章)	記憶庫 (本章)
活在當下	位於專案的 Agent Engine 中，且生命週期比所有程序都長
保留句子	保留當天擷取的事實，並依主題分類
依共用字詞尋找	依意義搜尋
附加	整合：如果新事實與舊事實相矛盾，則會修訂舊事實

被遺忘權

👉🖥 按下訊息方塊下方的「🔥 forget me」。

👀 三層樓的燈光熄滅，一層樓的燈光未熄滅：

	所持內容	後 🔥
三樓，卡片	她記得的內容，也就是 Memory Bank 從你的造訪記錄中擷取的資訊	不復存在，memories.delete一次一張
二樓的抽屜	user:case，也就是追蹤訪客每次造訪的記錄	已清除
辦公桌、紙條	本次就診的病歷副本	已清除
一樓，書籍	造訪本身，即每次造訪時的單一工作階段archive.db，以及工作階段中的每則訊息	未觸碰，計數不會移動

這些書籍是記錄：記錄了拜訪的日期和內容。這些卡片和抽屜就是記憶，代表她從這些訪視中學到的事物，並帶到下一次訪視。被遺忘權要求是針對記憶，也就是從某人身上衍生的事實，以及隨之而來的狀態。是否要一併刪除記錄，是基於稽核追蹤記錄或支援記錄等其他原因而做出的決定。本實驗室刻意保留記錄，讓您親眼見證兩者分離：記錄和記憶不同，忘記其中一項不會影響另一項。這是從另一側看到的 Vesper 門上句子。

ADK 記憶體抽象層具有 add_events_to_memory 和 search_memory。無法刪除。忘記是管理動作，而非代理程式動作，因此會存在於應用程式 (原始用戶端上的 archive/tower.py 和 memories.delete) 中，模型不會意外存取。代理程式是否會忘記資訊，與是否會記住資訊一樣，都是由您設計。

您建構及讀取的內容，以及這些內容的用途

該項目	說明	儲存位置
make_tower.py → AGENT_ENGINE in .env - built, not edited, nothing restarted	記憶體服務 (以服務形式)：部署決策，不在代理程式內	Agent Engine 上的 Vertex AI Memory Bank
tower_service(engine) - 你只讀取該檔案	相同的 Runner(memory_service=...) 插槽，但位於不同住家	archive/service.py
"allowed_topics": TOPICS (FILING) - 唯讀	系統可能會保留的內容 (在撰寫時決定，而非在提示中決定)	archive/topics.py + 基地台本身的設定
🔥 → memories.delete - 按下，而非輸入	忘記是應用程式動作；ADK 的記憶體 API 沒有刪除	archive/tower.py

這個階段會根據所說內容進行調整。一天過去了，事實也隨之產生，但經過主題的限制，書本始終沒有離開一樓。

7. GraphRAG

選用。

• 內容：一個指令碼會將山谷的過往載入 BigQuery、在資料倉儲內部生成嵌入項目，並在資料表上鋪設圖表，而不會移動任何資料列；然後向 Vesper 提出兩個問題，Vesper 有兩個受控查詢：一個用於查詢相似的聲音，一個用於查詢相關內容。
• 為什麼 - 聲音相似不等於已連線。向量會找出要搜尋的位置；圖表會找出附加的內容；答案則必須包含走過的路徑。
• 做法：bash scripts/season.sh 一次。本章節的其他內容僅供參考。

Vesper 的塔樓範圍僅限於您，(app_name, user_id) 施工時也是如此。其他人的造訪記錄並非她的記憶，再怎麼努力搜尋也不會改變這點。這些是山谷的財產，山谷將其存放在倉庫中。本季有 31 位訪客回報夜間 Q7 燈籠熄滅的問題，其中一位訪客找到了原因。本章會載入該倉庫，並將兩個修正後的查詢傳遞至該倉庫。

圖表 RAG

RAG 是「先檢索，再生成」：找出正確的記錄，交給模型，讓模型根據這些記錄回覆。一般 RAG 是依相似度檢索，也就是嵌入問題，然後提取最接近的記錄。這項功能會找出聽起來像問題的內容，也就是第 4 章的塔樓停止的位置。圖形 RAG 會在邊緣 (倉庫中已有的鍵) 之後新增第二個擷取步驟，從找到的任何相似項目擷取附加的項目。這兩個步驟分別回答不同的問題，本章會引導您提出這兩個問題：

點選 [下一步]	回答的問題	做法	本章
相似度	應該在哪裡查看相關資訊？	嵌入問題，VECTOR_SEARCH	season_search - 訪客未攜帶任何標記
遍歷	與此相關的內容為何？	MATCH 屬性圖中的路徑	season_known_issue - 一個固定 MATCH
代別	我該如何向訪客說明？	模型，並將路徑做為引用來源	她的答案

開始執行

這些季別會以純 CSV 格式出貨 season/(訪客、項目、要求、修正、季別)，就像支援系統匯出這些資料一樣。一個指令碼就能將資料一路帶進資料倉儲，而這也是本章中唯一執行的項目。

👉💻 在分頁 1 中 (約三分鐘；它會列印每個步驟，並在第一個失敗的步驟停止)：

cd ~/agent-valley-archive
bash scripts/season.sh

👀 結束時，塔樓的第四層會亮起，旁邊的圖例會顯示「開放」。

如果步驟 7 列印的內容為「does not have the permission to access or use the endpoint」，這是步驟 6 剛授予的角色，仍在傳播中；指令碼會等待該角色 (每次最多約兩分鐘，每次 15 秒)，並說明情況。如果指令碼放棄，請再次執行，因為其中的所有內容都是等冪。在步驟 8 完成前，四樓會鎖上，她也會說倉庫裡還沒有當季商品。

建構內容 - 唯讀

唯讀，無法執行任何動作。下列每個陳述式都已在 scripts/season.sh 內依序執行。這些指令碼是印出來供您閱讀，而不是貼到 bq 中；本章節只會執行指令碼。

1 · 資料 (含類型)。一個 bucket、五個資料表，每個資料表都有一個 bq load，且結構定義明確。這是倉儲，資料欄有名稱和類型：

bq load --replace --source_format=CSV --skip_leading_rows=1 archive.asks gs://.../asks.csv id:STRING,visitor_id:STRING,item_id:STRING,day:STRING,season:STRING,said:STRING

👀 預期 34會詢問：三十一個燈籠，以及本季發生的其他三件事，因此資料列數並非燈籠數。

2.意義，在適當位置。連線可讓 BigQuery 呼叫 Vertex AI；接著，嵌入模型就是一個陳述式，且每個要求都會嵌入所在位置，不必匯出，也不必使用管道：

CREATE OR REPLACE MODEL archive.embedder REMOTE WITH CONNECTION `US.vertex_conn`
  OPTIONS (ENDPOINT = "gemini-embedding-001");

CREATE OR REPLACE TABLE archive.ask_embeddings AS
  SELECT id, content, ml_generate_embedding_result AS embedding
  FROM ML.GENERATE_EMBEDDING(MODEL archive.embedder, (SELECT id, said AS content FROM archive.asks));

👀 預期 34, 3072：每個要求現在都是 3072 維度的向量，位於來源資料表旁邊。然後指令碼會根據意義提出一個問題：

SELECT base.content, ROUND(distance, 3) AS distance
FROM VECTOR_SEARCH(TABLE archive.ask_embeddings, "embedding",
  (SELECT ml_generate_embedding_result FROM ML.GENERATE_EMBEDDING(
     MODEL archive.embedder, (SELECT "the flame keeps dying on me once the sun is down" AS content))),
  top_k => 3)

👀 預期 (已驗證)：三份副本「天黑後就會斷線，而我只有在天黑後才需要使用」- 距離 0.648。與問題沒有任何共同字詞。這就是相似度步驟：找到要尋找的內容。但並未說明這三者是否與這位訪客的燈籠相連。

3 · 連接，鋪在桌子上。這五個表格已是圖表，無須建構，只要執行山谷即可。資料表中的資料列是「事物」，也就是節點資料表：訪客、項目、修正。資料表中的每一列都是「關係」，因此是邊緣資料表：一個要求就是一位訪客攜帶一項物品。relation而「燈籠」同時是這兩者，燈籠是「事物」，而燈籠的 mark 則是將燈籠與批次綁在一起的要素。items這個季度唯一沒有出貨的資料表是批次本身：沒有人將「q7」記錄為資料列，這是三十一列的共同點。一個 SELECT DISTINCT，而且該項目存在。指令碼的最後兩個步驟：

CREATE OR REPLACE TABLE archive.marks AS SELECT DISTINCT mark FROM archive.items;

CREATE OR REPLACE PROPERTY GRAPH archive.season_graph
  NODE TABLES (
    archive.visitors AS Visitor KEY (id)   PROPERTIES (id, name, species),
    archive.items    AS Item    KEY (id)   PROPERTIES (id, kind, mark),
    archive.marks    AS Mark    KEY (mark) PROPERTIES (mark),
    archive.fixes    AS Fix     KEY (mark) PROPERTIES (mark, what, found_by, day))
  EDGE TABLES (
    archive.asks  AS asked   KEY (id)   SOURCE KEY (visitor_id) REFERENCES Visitor (id)
                                        DESTINATION KEY (item_id) REFERENCES Item (id)
                                        PROPERTIES (day, season, said),
    archive.items AS stamped KEY (id)   SOURCE KEY (id) REFERENCES Item (id)
                                        DESTINATION KEY (mark) REFERENCES Mark (mark),
    archive.fixes AS fixed   KEY (mark) SOURCE KEY (mark) REFERENCES Mark (mark)
                                        DESTINATION KEY (mark) REFERENCES Fix (mark))

將其視為地圖：

(Visitor) ──asked──▶ (Item) ──stamped──▶ (Mark) ──fixed──▶ (Fix)
 who came             what they          the batch          what was wrong
                      brought            it belongs to      with the batch

未移動任何資料列。BigQuery 中的屬性圖是具有方向的檢視區塊：資料表會保留在原處；陳述式會指出哪些資料欄是鍵，哪些是箭頭。圖表會遭到捨棄，但表格不會受到影響。

然後是步行：

SELECT * FROM GRAPH_TABLE(archive.season_graph
  MATCH (m:Mark)<-[:stamped]-(i:Item)<-[a:asked]-(v:Visitor)
  WHERE m.mark = "q7"
  OPTIONAL MATCH (m)-[:fixed]->(f:Fix)
  RETURN m.mark AS mark, COUNT(DISTINCT v.id) AS visitors,
         COUNT(DISTINCT a.said) AS things_said, ANY_VALUE(f.what) AS fix)

👀 如果專案有 Enterprise 預留項目，預期會發生以下情況：

mark  visitors  things_said  fix
q7    31        10           the wicks in the q7 batch were dipped too shallow — they drown in the oil and starve in an hour

在一般的隨選專案中，這項陳述會遭到拒絕 (方塊後方的附註會說明原因)，腳本也會說明並結束。她仍會取得這些資料列。

也就是 GQL，這是 ISO 圖形查詢語言，您可能在其他圖形資料庫中見過 MATCH，現在則位於一般的 SELECT 內。這個模式是一句話：從標記處開始；退回每個蓋有標記的項目；再次退回詢問每個項目的人；如果標記有修正，則向前一步。OPTIONAL MATCH 可避免沒有修正的標記消失，本季有三個標記沒有修正。SQL 中有三個聯結，但圖形查詢新增的內容是，可從陳述式讀取走訪的形狀，而這個形狀就是她會提供給訪客的引用內容。

版本。BigQuery 圖形查詢 (GRAPH_TABLE) 需要企業版或 Enterprise Plus 預留位置。在一般的隨選專案中，系統會拒絕導覽，並顯示「BigQuery Graph 查詢需要 Enterprise 或 Enterprise Plus 版本的預留項目」。由於表格和圖表已就位，因此指令碼會列印該內容並完成作業，而工具接著會走訪與三個 SQL 聯結相同的資料列 (asks ⋈ items ⋈ visitors ⟕ fixes)，並在 walked 欄位中說明。無論如何，她的答案和路徑都相同。如果 CREATE PROPERTY GRAPH 本身遭到拒絕，工具會回答 locked，並提供執行步驟，而不是猜測。

她如何閱讀內容 - 僅供閱讀

唯讀。兩個函式和一個常數，已在 archive/season/__init__.py 中。Vesper 會呼叫這些函式，但您不會。

👉📖 開啟 archive/season/__init__.py。兩個函式和一個常數，且都不會採用查詢。常數優先 - 這是整個遍歷：

GQL = """
SELECT * FROM GRAPH_TABLE(`{ds}.season_graph`
  MATCH (m:Mark)<-[:stamped]-(i:Item)<-[a:asked]-(v:Visitor)
  WHERE m.mark = @mark AND a.season = @season
  OPTIONAL MATCH (m)-[:fixed]->(f:Fix)
  RETURN v.name AS who, a.said AS said, a.day AS day, f.what AS what, f.found_by AS found_by)
ORDER BY day"""

👀 按照箭頭方向，將 MATCH 行讀成一個句子：

該作品	以文字表示
(m:Mark)	從特定時間戳記開始播放：q7
<-[:stamped]-(i:Item)	追溯到蓋有該戳記的每個項目
<-[a:asked]-(v:Visitor)	再次向詢問各項資訊的人員回報
OPTIONAL MATCH (m)-[:fixed]->(f:Fix)	如果標記有修正內容，則可直接前往該內容
@mark、@season	這兩項是唯一會變動的項目，模型會填入其中一項，但絕不會寫入路徑

• GQL：您剛才讀取的 MATCH，以 @mark 和 @season 做為參數。這是她唯一能做的散步。
• season_search(text)：來自陳述式 2 的 VECTOR_SEARCH，已重新加入說話者和他們帶來的物品標記。負責說明要查看的位置。
• season_known_issue(mark, season) - 執行 GQL。一個標記：數量、所說內容、原因、發現者和路徑。
• SQL：與三個聯結相同的走法，只會在專案版本拒絕 GRAPH_TABLE 時執行；工具會在 walked 中說明。

只有在倉儲存在時，她才會持有這兩項項目：tools_for_vesper() 會在 season.is_open() 為 true 時將其交給她，而服務會在每則訊息中重新匯入該檔案。archive/agent.py在劇本中，四樓是鎖住的，她完全無法抵達。描述自己的困境絕不會被誤認為是詢問其他人的問題。

Vesper 絕不會編寫 GQL 或 SQL。這兩項陳述內容都是固定的，模型會提供一個參數。請閱讀她的指示：agent.py給定標記，然後步行。如果沒有，請先搜尋，然後標示最接近的相符項目，再逐步驗證，切勿將相似的內容當成任何事證。也就是本章開頭的表格，做為政策：向量會找出要搜尋的位置，圖表會找出連結的內容，模型則會提供附有引文路徑的答案。這也是新房間的第三週句子：the model fills in the form, the code moves the sparks.

問她

👉🖥 四樓已開放。請她以訪客身分提出要求：

Has anyone else had a q7 lantern go out at night?

👀 她回覆了，另外三十一人也回覆了，大多數人表示火焰很小，一小時後就熄滅了。Marlow 發現蠟燭芯浸得不夠深，而答案的最後一行就是路徑。這是她的輸出內容，請閱讀，但不要傳回給她：

mark q7 → 31 visits this season → 10 different things said → the wicks in the q7 batch were dipped too shallow — they drown in the oil and starve in an hour

路徑就是引文。其中的每個躍點都是圖表中的邊，而邊就是金鑰，因此任何人都可以再次走訪，並取得相同的 31。任何人皆無法再次進行相似度評估。如果她在路徑前表示資料列是透過三個聯結傳回，因為專案沒有圖表預留空間，這就是專案版本拒絕 GRAPH_TABLE 的原因，資料列和路徑相同。

👉🖥 現在請將標記排除在外，傳送以下內容：

Has anyone else had a lantern that keeps dying once the sun is down?

👀 她得到相同的三十一分，路徑也相同。改變的是路徑：season_search 先跑，找到五位相似的訪客 (每位都攜帶 q7)，然後才走。「類似」並非連線，而是要尋找的內容。

這就是 31 的由來。第 1 到 4 章會產生使用的所有事實，因此本實驗室可獨立運作。本章節將矽谷的過去視為資料，而非捷徑，因為這就是定義。機構記憶是其他人的記憶，而您當時並不在場。

載入的內容和用途

該項目	說明	儲存位置
bq load (含明確結構定義) - 執行，但未寫入	倉庫：含有名稱和類型的資料欄	archive.visitors / items / asks / fixes / seasons
ML.GENERATE_EMBEDDING + VECTOR_SEARCH	相似度步驟 - 應查看的位置	archive.ask_embeddings，embedder 模型
CREATE PROPERTY GRAPH - 未移動任何資料列	遍歷步驟：連結的內容；表格會變成節點和箭頭	archive.season_graph
GQL in archive/season/__init__.py - 一個參數	她唯一能走的道路，而這條路就是引文	season_known_issue(mark)

幾十位訪客並非購買倉庫的理由。本章節的重點是查詢的形狀，而非規模。將這個圖表放大一千倍，MATCH 也不會改變。

8. 關閉

三條線、一座塔、一個倉庫，共四層樓。沒有重新啟動任何項目。

階梯	你所做的動作	購買的商品
ONE	tool_context.state[CASE] = case - 編輯	任何滑動：狀態是由程式碼所寫
二	CASE = "user:case" - 編輯	跟隨訪客的導覽匣
歸檔	await ctx.add_events_to_memory(..., custom_metadata=FILING) - 讀取，但未寫入	說過的話、保留的內容
三	found = await ctx.search_memory(query) - 編輯	保留的內容、要求的事項 - 系統不會記住檔案
塔	make_tower.py，然後在 .env 中按一下 AGENT_ENGINE，由一行程式碼建構及連線，無需重新啟動	蒸餾塔，並在夜間存活
規則	allowed_topics in FILING - read, not written	只保留應保留的內容
賽季	season.sh - 已載入、嵌入原位、疊加圖表、與一人同行 MATCH	其他人的造訪記錄 (依意義和連結)

每個零件的更換情形

ADK 2	您會改寫的內容	以及費用
session.state + 一項工具，由 SqliteSessionService 保留	聊天迴圈旁的 dict，自行封存至磁碟	模型無法讀取，而您會撰寫履歷和鎖定
user: 前置字串	使用者資料表，以及每次輪流的聯結	每次都要決定金鑰的歸屬位置
add_events_to_memory + search_memory 位於函式節點中	傾印轉錄稿的 Cron，以及決定何時查看的模式	它會傾印，不會蒸餾，而且您永遠不會看到未查看的時間
VertexAiMemoryBankService + allowed_topics	向量儲存區、擷取提示、合併工作，以及提示中的「請勿記住瑣事」	三項服務，且這項規則會持續生效，直到模型認為情況有異為止
VECTOR_SEARCH + 一個固定的 GQL MATCH	匯出、嵌入其他位置、圖形資料庫、同步工作，以及模型撰寫 SQL	資料會離開資料倉儲以供解讀，而當顧客執行

三個問題，在第一個「是」之後停止

1. 明天還重要嗎？否 → 不保留任何內容。這項功能會隨著對話開始和結束。
2. 函式可以檢查嗎？是 → 導覽匣。程式碼會寫入，每個回合都會讀取，且任何句子都無法變更。
3. 其他情況 → 塔樓。從對話內容中擷取資訊，在需要時提供，並根據後續對話內容修正。

單一句子

記錄不是記憶體。記憶記錄包含兩項決定：要保留哪些內容，以及何時查看。內容類型則決定了內容要放在哪個樓層。

事實和偏好設定應分別儲存在不同商店。

👀 每個樓層都亮著燈。畫面頂端會顯示你的熟人。護照上會蓋上「封存」戳記，第五週則會開放夜市。屆時 Nix 會即時大聲朗讀舞台上的內容，而塔樓所知的一切都會跟著你。