Mori

DOCS

Annuli 記憶與年輪

VAULT · MEMORY · SOUL TOKEN

Annuli 是 Mori 的可選反思服務。沒裝 Annuli 時,Mori 仍會使用本機 ~/.mori/memory/ fallback；接上 Annuli 後,長期記憶、對話事件、 SOUL 與年輪會改走 ~/mori-universe/spirits/<name>/ vault。

一般使用者建議先用 Mori 內建的一鍵流程。 到 Deps 安裝「Annuli 反思服務 runtime」,再到 Annuli tab 按「一鍵啟用」。新版 Mori 會自動產生並同步 soul_token;不需要去網站申請 token。

1. Annuli 解鎖什麼

SOUL.md:角色核心身分,由 vault 保存。
MEMORY.md:使用者明確要求 Mori 記住的長期記憶。
events:每天的 user / assistant 對話事件。
rings:按下 sleep 後產生的反思年輪。

Annuli 不是雲端服務。預設路徑在你的電腦: Windows runtime 在 %USERPROFILE%\.mori\annuli; Linux / macOS runtime 在 ~/mori-universe/annuli。 vault 預設在 ~/mori-universe/spirits/mori。

2. Windows 手動安裝 Annuli runtime

如果 Deps tab 還沒有自動安裝功能,在 PowerShell 執行:

mkdir $env:USERPROFILE\.mori -Force
if ((Test-Path $env:USERPROFILE\mori-universe\annuli) -and !(Test-Path $env:USERPROFILE\.mori\annuli)) {
  Move-Item $env:USERPROFILE\mori-universe\annuli $env:USERPROFILE\.mori\annuli
}
if (!(Test-Path $env:USERPROFILE\.mori\annuli)) {
  git clone https://github.com/yazelin/annuli $env:USERPROFILE\.mori\annuli
}
cd $env:USERPROFILE\.mori\annuli
uv venv .venv --python 3.11
uv pip install --python .venv\Scripts\python.exe -e .

$token = .\.venv\Scripts\python.exe -c "import secrets; print(secrets.token_hex(32))"
if (!(Test-Path .env) -or !(Select-String -Path .env -Pattern '^ANNULI_SOUL_TOKEN=.' -Quiet)) {
  Add-Content .env "ANNULI_SOUL_TOKEN=$token"
}

接著回 Mori Desktop:打開 Annuli tab,按「一鍵啟用」。新版 Mori 會讀取 annuli\.env 裡的 ANNULI_SOUL_TOKEN,並寫進 %USERPROFILE%\.mori\config.json 的 annuli.soul_token。

3. Linux / macOS 安裝 Annuli runtime

建議直接用 Mori 的 Deps tab 安裝。手動等價指令:

ANNULI="$HOME/mori-universe/annuli"
mkdir -p "$HOME/mori-universe"
git clone https://github.com/yazelin/annuli "$ANNULI"
cd "$ANNULI"
uv venv "$ANNULI/.venv" --python 3.11
uv pip install --python "$ANNULI/.venv/bin/python" -e "$ANNULI"

touch "$ANNULI/.env"
if ! grep -q '^ANNULI_SOUL_TOKEN=.' "$ANNULI/.env"; then
  TOKEN="$("$ANNULI/.venv/bin/python" -c 'import secrets; print(secrets.token_hex(32))')"
  printf '\nANNULI_SOUL_TOKEN=%s\n' "$TOKEN" >> "$ANNULI/.env"
fi

4. SOUL token 是什麼

soul_token 是本機隨機 secret,不是平台帳號 token,也不是 API key。它的目的只有一個:防止 LLM 或未授權 caller 直接寫入 SOUL / MEMORY。

兩邊必須完全一致:

位置	欄位
`~/.mori/config.json` 或 `%USERPROFILE%\.mori\config.json`	`annuli.soul_token`
`~/mori-universe/annuli/.env` 或 `%USERPROFILE%\.mori\annuli\.env`	`ANNULI_SOUL_TOKEN`

{
  "annuli": {
    "enabled": true,
    "endpoint": "http://localhost:5000",
    "spirit_name": "mori",
    "user_id": "yazelin",
    "soul_token": "同 ANNULI_SOUL_TOKEN 的值",
    "timeout_secs": 10
  }
}

5. 啟動與驗證

若 Mori 是從 Annuli tab 一鍵啟用,它會自行嘗試啟動 localhost Annuli server。若要手動啟動:

# Windows PowerShell
cd $env:USERPROFILE\.mori\annuli
.\.venv\Scripts\python.exe main.py admin --port 5000

# Linux / macOS
cd ~/mori-universe/annuli
.venv/bin/python main.py admin --port 5000

驗證 server 是否活著:

curl http://localhost:5000/health

回應裡 soul_token_configured 應該是 true。如果是 false,代表 Annuli server 啟動時沒有讀到 ANNULI_SOUL_TOKEN;重啟 Annuli 或重啟 Mori。

6. 常見錯誤

`soul_token config.json 沒設`

這是 Mori Desktop 端還沒送 request 前就擋下來。修法:到 Config tab 的 Annuli subtab 填 soul_token,或回 Annuli tab 按新版「一鍵啟用」讓 Mori 自動補。

`ANNULI_SOUL_TOKEN 未設` 或 `X-Soul-Token 不符`

這是 Annuli server 端拒絕。修法:確認 .env 與 config.json 的 token 完全一致,然後重啟 Annuli server。

Annuli tab 顯示 unreachable

確認 endpoint 是 http://localhost:5000,沒有尾端 slash。
確認 curl http://localhost:5000/health 有回應。
若 500 error,看 Annuli process terminal 的 traceback。

7. 文件狀態

舊的 docs/design/annuli-wave3-integration.md 是工程 checklist, 不是一般使用者手冊,部分敘述也已落後於目前實作。安裝與故障排除以本頁為準。