v0.3.0 — departments, versioned migrations, team leader role

What you must do

0.3.0 renames the "instance" to the "department", in the API, the settings and the stored data. An AgentMemory server holds departments, a department holds teams, and a team holds members and agents. Update the server and every client together:

1. Stop the agents that write to the server. If you run several memory-core replicas, stop all of them: an older replica cannot read migrated data.

2. On the server:

   git fetch --tags && git checkout v0.3.0
   ./upgrade.sh

   upgrade.sh backs up the data, renames CORE_INSTANCE_ID to CORE_DEPARTMENT_ID in .env and rebuilds. memory-core migrates the stored data as it starts. The migration is one-way: going back to 0.2.x means restoring that backup.

3. Update amem on every client machine. It rewrites service_id to department_id in client.json by itself. In Claude Code, if you had set Service ID, set Department ID to the same value.

A client older than 0.3.0 gets 401: "x-memory-service-id was renamed in 0.3.0; update the client".

	Before	0.3.0
Header	x-memory-service-id	x-memory-department-id
amem	service_id, AMEM_SERVICE_ID, --service-id	department_id, AMEM_DEPARTMENT_ID, --department-id
.env / Panel	CORE_INSTANCE_ID	CORE_DEPARTMENT_ID
memory-core.yaml	maxOpenInstances, max*PerInstance	maxOpenDepartments, max*PerDepartment (old names are rejected by name)
API	/v3/instance/destroy, meta/instance-quota/get, internal/meta/user/list-by-instance	the department equivalents
Team roles	admin, member, reviewer	admin, leader, member (reviewers become members)

Full guide: docs/UPGRADE.md → To 0.3.0.

What's new

Versioned storage migrations (#32)

• Stored data now carries a version:

  • SQLite user_version;
  • Postgres agent_memory.schema_migrations;
  • Redis {prefix}:schema_version.

• memory-core migrates at start-up under a lock, so with several replicas only one migrates. memory-server migrate does the same explicitly and also migrates every SQLite department up front.

• Migration 1 renames what 0.2 stored:

  • the data directory;
  • system.db;
  • the Postgres registry, prompt targets and quota names (keeping your values);
  • Redis indexes, state documents, queued jobs and dead letters.

  Migration 2 turns reviewers into members.

• How to add the next migration: docs/ops/SCHEMA-MIGRATIONS.md.

Team leader role and role-based visibility (#33)

• A leader uses memory like a member and sees how the whole team's distillation is doing: pipeline state, generation logs and dead letters of every member. A leader cannot open other members' conversations or facts, and cannot manage members.

• Pipeline state, generation logs and dead letters are now filtered by who asks:

  Caller	Sees
  Server API key alone, or a system admin	The whole department
  Team admin or leader	Their whole team
  Member	The team's shared L2/L3 work, and their own

  Before 0.3.0, every signed-in user saw every scope of the department.

• Redriving dead letters with a user key needs a system admin.

• /health no longer shows the worker's last error.

• Panel: the scope table shows team, agent and user names. A row links to the memory browser (/memory?team=…&agent=…&user=…) only when you may read it.

Fixes

• pipeline/status applied limit before filtering. Session rows shared one table key, and l2_pending was null on session rows (#33).
• When the distillation LLM is a CLI (claude, agy, …) and it answers nothing, the error now includes what it wrote to stderr (#31).

Docs: MULTI-TENANCY.md is now COLLABORATION.md (departments, teams, members and agents). The Bearer key is called the server API key: it covers every department.

---

你需要做的事

0.3.0 把「instance」改名為「部門（department）」，API、設定和儲存的資料都一起改。 一台 AgentMemory 伺服器容納多個部門，部門裡有團隊，團隊裡有成員和 agent。伺服器和所有 client 要一起更新：

1. 停掉會寫入伺服器的 agent。如果跑了多個 memory-core replica，要全部停掉：舊版 replica 讀不懂遷移後的資料。

2. 在伺服器上執行：

   git fetch --tags && git checkout v0.3.0
   ./upgrade.sh

   upgrade.sh 會備份資料、把 .env 的 CORE_INSTANCE_ID 改成 CORE_DEPARTMENT_ID，然後重建服務。memory-core 啟動時會遷移儲存的資料。遷移只能往前：要回到 0.2.x，必須還原那份備份。

3. 更新每台 client 機器上的 amem，它會自己把 client.json 的 service_id 改成 department_id。在 Claude Code 裡，如果之前設定過 Service ID，請把 Department ID 設成同樣的值。

0.3.0 之前的 client 會收到 401，訊息是「x-memory-service-id was renamed in 0.3.0; update the client」。

	之前	0.3.0
Header	x-memory-service-id	x-memory-department-id
amem	service_id、AMEM_SERVICE_ID、--service-id	department_id、AMEM_DEPARTMENT_ID、--department-id
.env / Panel	CORE_INSTANCE_ID	CORE_DEPARTMENT_ID
memory-core.yaml	maxOpenInstances、max*PerInstance	maxOpenDepartments、max*PerDepartment（設定檔還用舊名稱時，會直接報錯並指出新名稱）
API	/v3/instance/destroy、meta/instance-quota/get、internal/meta/user/list-by-instance	對應的 department 路由
Team 角色	admin、member、reviewer	admin、leader、member（reviewer 改為 member）

完整說明：docs/UPGRADE.zh-tw.md →「升級到 0.3.0」。

新功能

有版本的儲存遷移（#32）

• 儲存的資料開始記錄版本：

  • SQLite 用 user_version；
  • Postgres 用 agent_memory.schema_migrations；
  • Redis 用 {prefix}:schema_version。

• memory-core 啟動時會在 lock 之下自動遷移，所以有多個 replica 時只會由一個執行。memory-server migrate 可以手動執行同樣的步驟，也會一次把每個 SQLite 部門都遷移完。

• 第 1 號遷移改寫 0.2 存下的資料：

  • 資料目錄；
  • system.db；
  • Postgres 的 registry、prompt 目標和配額名稱（保留你設定的值）；
  • Redis 的 index、狀態文件、佇列中的 job 和 dead letter。

  第 2 號遷移把 reviewer 改成 member。

• 如何新增遷移：docs/ops/SCHEMA-MIGRATIONS.zh-tw.md。

Team leader 角色與依角色檢視運作狀態（#33）

• Leader 像 member 一樣使用記憶，另外可以看到整個 team 的蒸餾運作情形：每位成員的管線狀態、生成紀錄和 dead letter。Leader 不能開啟其他成員的對話或事實，也不能管理成員。

• 管線狀態、生成紀錄和 dead letter 會依查詢者篩選：

  呼叫者	看得到
  只帶伺服器 API key，或系統管理者	整個部門
  Team admin 或 leader	自己的整個 team
  Member	team 共用的 L2/L3 工作，以及自己的工作

  0.3.0 之前，任何登入的使用者都看得到部門內的所有範圍。

• 帶 user key 重跑 dead letter 需要系統管理者。

• /health 不再顯示 worker 最後一次的錯誤。

• Panel：範圍表格顯示 team、agent 和使用者的名稱。只有你有權讀取的那一列，才會連到記憶瀏覽器（/memory?team=…&agent=…&user=…）。

修正

• pipeline/status 原本先取筆數再篩選。同一個 agent 的多個 session 在表格裡共用同一個 key。session 那幾列的 l2_pending 是 null（#33）。
• 蒸餾用的 LLM 是 CLI（claude、agy 等）且沒有輸出任何內容時，錯誤訊息現在會附上它寫到 stderr 的內容（#31）。

文件：MULTI-TENANCY.md 改名為 COLLABORATION.zh-tw.md（部門、團隊、成員與 agent）。Bearer key 統一叫做伺服器 API key，它涵蓋所有部門。