Skip to content

Agent Memory v0.2.3

Choose a tag to compare

View all tags
@github-actions github-actions released this 20 Oct 13:31
· 39 commits to main since this release
Immutable release. Only release title and notes can be modified.
v0.2.3
6d3b93d
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Why this release

Distillation could fail silently, and the work it lost could not be recovered. On a real install, the LLM that distils memories ran out of quota. 93 pipeline jobs (L1, L2, L3, skill extraction) failed every retry and were set aside as dead letters. Nothing showed it:

  • A failed L1/L2/L3 run left no generation log, and neither did a run that wrote nothing.
  • A dead letter was stored without its error. With the local coordination backend it was only counted, then lost.
  • There was no way to put a dead letter back in the queue; it took editing Redis by hand.
  • The logs named only the command (cli:agy), not the model that ran.

v0.2.3 makes all of this visible and recoverable.

Upgrading

No data or configuration changes. From any version since 0.1.1:

git fetch --tags && git checkout v0.2.3
docker compose up -d --build

Dead letters written before the upgrade remain readable but have no error recorded. Update amem on the clients if you want skip_prompt_prefixes (below).

What's new and fixed

Distillation runs and dead letters (#28)

  • Every run is logged. Each L1/L2/L3 run that reaches the LLM is logged as succeeded, empty (the LLM answered but nothing was written) or failed with its error.

  • The real model is recorded, including a CLI's --model, e.g. cli:agy:gemini-3.8-flash-high.

  • Dead letters keep their last error and time.

    • With Redis they are shared by all replicas.
    • With local coordination, the newest 1,000 are kept in memory.

  • Panel → Dashboard → Distillation:

    • the LLM in use;
    • runs per layer over 24 h with the failure rate;
    • the latest failures;
    • dead letters per kind;
    • a Re-run button for system admins.

    Generation logs gain the empty status, plus model, latency, session and error columns. #/logs?status=failed opens filtered.

  • CLI on the server:

    docker compose exec memory-core memory-server generations
docker compose exec memory-core memory-server dead-letters
docker compose exec memory-core memory-server dead-letters redrive --limit 10

  • API:

    • POST /v3/memory-generation-log/summary;
    • POST /v3/pipeline/dead-letter/{list,redrive}.

    A redrive queues jobs again as first attempts, oldest first. With several replicas, each one is taken by one node only.

  • Guide: docs/ops/DISTILLATION.md explains what is recorded, where to look, common LLM failures, changing the model, and redriving gradually.

Fixes and smaller changes

  • migrate-to-postgres.sh (#25): it now honours AGENT_MEMORY_POSTGRES_URL given on the command line with MIGRATE_TARGET=postgres-url. Before, the empty value in .env replaced it, which was the known issue in v0.2.2.
  • amem skip_prompt_prefixes (#27, @blackhorseya): prompts that start with a configured prefix, such as messages an orchestrator types into an agent, are neither recalled for nor captured. The setting can come from AMEM_SKIP_PROMPT_PREFIXES, the Claude Code plugin option, or client.json. It is empty by default.

Thanks to @blackhorseya for #27.

為什麼要發這個版本

蒸餾可能在沒人發現的情況下失敗，遺失的工作也無法補回。 在一個實際運作的安裝上，負責蒸餾記憶的 LLM 額度用完了。93 個 pipeline job（L1、L2、L3、skill 擷取）每次重試都失敗，被移到 dead letter，但完全沒有跡象：

  • 失敗的 L1/L2/L3 執行不會留下生成紀錄，沒有寫出任何東西的執行也一樣。
  • Dead letter 沒有保存錯誤原因。使用 local coordination backend 時只會計數，然後就消失。
  • 沒有辦法把 dead letter 重新排回佇列，只能手動修改 Redis。
  • 紀錄裡只有指令名稱（cli:agy），看不出實際用的是哪個模型。

v0.2.3 讓這些狀況都看得到，也都能補救。

升級

資料和設定都沒有改變。從 0.1.1 之後的任何版本升級：

git fetch --tags && git checkout v0.2.3
docker compose up -d --build

升級前寫入的 dead letter 仍然讀得到，但沒有記錄錯誤原因。如果要使用 skip_prompt_prefixes（見下方），請更新 client 端的 amem。

新功能與修正

蒸餾執行紀錄與 dead letter（#28）

  • 每次執行都有紀錄。 每一次呼叫到 LLM 的 L1/L2/L3 執行，都會記錄為 succeeded、empty（LLM 有回應但沒有寫出任何東西）或 failed（附上錯誤）。

  • 記下實際使用的模型，包含 CLI 的 --model，例如 cli:agy:gemini-3.8-flash-high。

  • Dead letter 會保留最後一次的錯誤和時間。

    • 使用 Redis 時由所有 replica 共用。
    • 使用 local coordination 時，在記憶體中保留最新的 1,000 筆。

  • Panel → Dashboard → Distillation：

    • 目前使用的 LLM；
    • 過去 24 小時各層的執行次數與失敗率；
    • 最近的失敗；
    • 各類 job 的 dead letter；
    • system admin 可以使用的 Re-run 按鈕。

    Generation logs 新增 empty 狀態，以及模型、延遲、session、錯誤等欄位。#/logs?status=failed 會直接套用篩選。

  • 伺服器上的 CLI：

    docker compose exec memory-core memory-server generations
docker compose exec memory-core memory-server dead-letters
docker compose exec memory-core memory-server dead-letters redrive --limit 10

  • API：

    • POST /v3/memory-generation-log/summary；
    • POST /v3/pipeline/dead-letter/{list,redrive}。

    重跑時會把 job 當成第一次嘗試重新排入佇列，最舊的先跑。有多個 replica 時，每一筆只會由其中一個節點取走。

  • 指南：docs/ops/DISTILLATION.zh-tw.md 說明會記錄哪些資訊、在哪裡查看、常見的 LLM 失敗原因、如何更換模型，以及如何分批重跑。

修正與其他調整

  • migrate-to-postgres.sh（#25）：搭配 MIGRATE_TARGET=postgres-url 時，現在會採用在指令上傳入的 AGENT_MEMORY_POSTGRES_URL。之前 .env 裡的空值會把它覆蓋掉，這就是 v0.2.2 的已知問題。
  • amem 的 skip_prompt_prefixes（#27，@blackhorseya）：以設定的前綴開頭的 prompt，例如協調程式自動輸入給 agent 的訊息，不會觸發召回，也不會被擷取。這個設定可以來自 AMEM_SKIP_PROMPT_PREFIXES、Claude Code plugin 選項或 client.json，預設為空。

感謝 @blackhorseya 貢獻 #27。

Contributors

blackhorseya
Assets 8
Loading