@shadowforge0/aquifer-memory 1.8.1 → 1.9.1

package/.env.example

@@ -11,6 +11,7 @@ AQUIFER_MEMORY_SERVING_MODE=legacy
 # AQUIFER_MEMORY_SERVING_MODE=curated
 # AQUIFER_MEMORY_ACTIVE_SCOPE_KEY=project:example
 # AQUIFER_MEMORY_ACTIVE_SCOPE_PATH=global,project:example
+# AQUIFER_MEMORY_ALLOWED_SCOPE_KEYS=global,project:example
 
 # Optional Codex active-session checkpoint heartbeat policy.
 # AQUIFER_CODEX_CHECKPOINT_CHECK_INTERVAL_MINUTES=10

package/README.md

@@ -67,28 +67,67 @@ Claude Code, Claude Desktop, or any MCP-capable client — drop this into `.mcp.
 
 Or run it directly: `DATABASE_URL=... EMBED_PROVIDER=ollama npx aquifer mcp`. The MCP server itself stays strict about env; `quickstart` autodetect is the try-it path, not the production one.
 
-Keep `AQUIFER_MEMORY_SERVING_MODE=legacy` for first rollout. Switch to `curated` only when you want `session_recall` and `session_bootstrap` to serve active curated memory; `evidence_recall` stays the explicit audit/debug lane. Rollback is just flipping env or config back to `legacy`.
+Keep `AQUIFER_MEMORY_SERVING_MODE=legacy` for first rollout. Switch to `curated` only when you want compatibility `session_recall` and `session_bootstrap` to serve active curated memory. Use `memory_recall` for explicit current-memory lookup, `historical_recall` for the historical/session plane, and `evidence_recall` for the audit/debug lane. Rollback is just flipping env or config back to `legacy`.
+
+Curated serving is scope-bound. `AQUIFER_MEMORY_ACTIVE_SCOPE_PATH` is the ordered inheritance path, while `AQUIFER_MEMORY_ALLOWED_SCOPE_KEYS` is the caller boundary. If `activeScopePath` is omitted, Aquifer defaults it to `global` plus the configured `activeScopeKey`, or to `global` alone when no active scope is configured. If `allowedScopeKeys` is omitted, Aquifer defaults it to that active scope path. Runtime requests outside that boundary are rejected before reading current memory rows.
 
 ### Common commands
 
 | Goal | Command |
 |---|---|
 | Verify setup | `npx aquifer quickstart` |
+| Run read-only governance diagnostics | `npx aquifer doctor --json` |
 | Inspect selected backend capabilities without DB connection | `AQUIFER_BACKEND=local npx aquifer backend-info --json` |
 | Start the MCP server | `npx aquifer mcp` |
 | Search memory manually | `npx aquifer recall "auth middleware"` |
+| Explain current-memory bootstrap selection | `npx aquifer explain bootstrap --active-scope-key project:aquifer --json` |
+| Explain current-memory recall selection | `npx aquifer explain memory --query "serving contract" --active-scope-key project:aquifer --json` |
+| Inspect finalized-session ledger rows | `npx aquifer finalization list --status finalized --json` |
+| Inspect operator ledgers | `npx aquifer operator status --json` |
+| Review current-memory feedback issues | `npx aquifer review queue --scope-key project:aquifer --feedback-type incorrect --json` |
+| Resolve a reviewed memory queue item | `npx aquifer review resolve --memory-id 42 --resolution resolved --reason "verified current" --expected-latest-issue-feedback-id 9 --json` |
 | Plan curated memory compaction | `npx aquifer compact --cadence daily --period-start 2026-04-27T00:00:00Z --period-end 2026-04-28T00:00:00Z` |
 | Generate a timer synthesis prompt | `npx aquifer operator compaction daily --include-synthesis-prompt --json` |
 | Apply reviewed timer synthesis candidates | `npx aquifer operator compaction daily --synthesis-summary-file /tmp/timer-summary.json --apply --promote-candidates --json` |
 | Generate a finalized-session checkpoint prompt | `npx aquifer operator checkpoint --scope-key project:aquifer --min-finalizations 10 --include-synthesis-prompt --json` |
 | Heartbeat-check an active Codex session for checkpoint work | `npx aquifer codex-recovery checkpoint-heartbeat --hook-stdin --scope-key project:aquifer` |
+| Inspect pending Codex checkpoint spool files | `npx aquifer codex-recovery checkpoint-spool-status --json --limit 10` |
 | Preview a Codex UserPromptSubmit heartbeat hook install | `npx aquifer codex-recovery checkpoint-heartbeat-hook --scope-key project:aquifer --hooks-path "$CODEX_HOME/hooks.json" --json` |
-| Inspect storage health | `npx aquifer stats` |
+| Check memory readiness | `npx aquifer stats` |
+| Check saved-content preparation | `npx aquifer backlog --json` |
+| Dry-run a saved-content policy decision | `npx aquifer backlog --plan skip --status pending --source openclaw-mcp` |
 | Enrich pending sessions | `npx aquifer backfill` |
 
-Timer synthesis output is candidate material until an operator applies it with
-`--promote-candidates`; it does not become active curated memory from the
-prompt or summary file alone.
+`stats`, `backlog`, MCP `memory_stats`, and MCP `memory_pending` default to the
+same public status surface: `Aquifer status` or `Saved content status`, plus
+`Available`, `Attention`, and `Action` where relevant. Use `stats --diagnostics`,
+`backlog --diagnostics`, or MCP `diagnostics: true` for raw counters, buckets,
+guidance, and samples.
+
+Reviewed timer synthesis is gated before promotion. Candidate items must carry
+`mergeKey`, `scopeClass`, `durability`, `promotionTarget`, and
+`sourceCanonicalKeys` that reference `sourceCurrentMemory`; runtime state also
+needs `staleAfter` or `validTo`. The temporal distillation gate rejects
+workspace/operator policy, transient material, unsupported promotion targets,
+invalid or missing source lineage, and duplicate merge keys before current
+memory promotion. `assistant_shaping` may target `assistant_behavior_memory`
+only when the item carries behavior-level abstraction metadata:
+`languageLevel=user_behavior`, `appliesBeyondSource=true`, `sourceBound=false`,
+and a `principle`. Project-specific source wording stays lineage/context
+material; serving memory uses the behavior principle.
+
+To serve user-level assistant behavior alongside a project, include the user
+scope in the active path, for example
+`AQUIFER_MEMORY_ACTIVE_SCOPE_PATH=global,user:mk,project:aquifer` with matching
+allowed scope keys. Applicable `assistant_shaping` records are pinned ahead of
+ordinary project current memory in bootstrap.
+
+Timer synthesis output is candidate material until an operator applies a
+reviewed synthesis summary with `--promote-candidates`; it does not become
+active curated memory from the prompt or summary file alone. The deterministic
+daily/weekly/monthly aggregate proposals in a dry-run are source-rollup
+material for review and ledger lineage only, and are blocked from normal active
+promotion unless a reviewed synthesis summary is attached.
 
 Checkpoint output follows the same boundary. `operator checkpoint` plans from
 finalized session summaries and only writes `checkpoint_runs` when you pass an
@@ -98,6 +137,28 @@ files: it first checks a tiny local scheduler marker, reads the transcript only
 when the time window is due, then writes local spool process material only when
 the message threshold is also due. It does not print prompt text by default and
 does not write DB memory.
+Use `codex-recovery checkpoint-spool-status --json` to inspect pending local
+spool files by session, coverage, byte size, and modified time without printing
+the checkpoint prompt text.
+
+Read-only governance commands are diagnostic surfaces. `doctor`,
+`finalization list|inspect`, `explain bootstrap|memory`, and
+`operator status|inspect` do not apply migrations, promote memory, mutate
+finalization status, reclaim operator leases, or add MCP tools. `review
+queue|inspect` is read-only with respect to memory truth, but uses the normal
+Aquifer migration gate because it depends on the resolution ledger schema. It
+derives an operator queue from curated memory feedback such as `incorrect`,
+`stale`, and `scope_mismatch` without printing raw transcripts, feedback notes,
+feedback metadata, or memory payloads. `review resolve` is the narrow write path
+for this surface: it appends a snapshot-bound resolution ledger row
+(`resolved`, `ignored`, or `deferred`) without mutating `memory_records` or
+rewriting feedback history. Newer issue feedback reopens the queue item. Use
+these commands to answer why a session did not finalize, why a current-memory
+row was selected or excluded, which visible memory rows need human review, and
+whether operator ledgers contain stale claims before running write paths.
+Explain output includes stable scope inheritance details for selected and
+excluded rows; non-selected rows redact `title` and `summary` so diagnostics
+cannot become a cross-scope content probe.
 
 Need LLM summarization, the knowledge graph, OpenAI embeddings, reranking, or operations details? See [docs/setup.md](docs/setup.md) and [Environment Variables](#environment-variables).
 
@@ -172,6 +233,7 @@ Sessions, summaries, turn-level embeddings, entity graph — all live in one dat
 | `AQUIFER_MEMORY_SERVING_MODE` | No | Public serving mode: `legacy` default, or opt-in `curated` | `curated` |
 | `AQUIFER_MEMORY_ACTIVE_SCOPE_KEY` | No | Default active curated scope for recall/bootstrap | `project:aquifer` |
 | `AQUIFER_MEMORY_ACTIVE_SCOPE_PATH` | No | Ordered curated scope path for inheritance | `global,project:aquifer` |
+| `AQUIFER_MEMORY_ALLOWED_SCOPE_KEYS` | No | Caller boundary for curated scope requests; defaults to the configured active scope path | `global,project:aquifer` |
 | `AQUIFER_CODEX_CHECKPOINT_CHECK_INTERVAL_MINUTES` | No | Active Codex checkpoint heartbeat time gate (default: `10`) | `10` |
 | `AQUIFER_CODEX_CHECKPOINT_EVERY_MESSAGES` | No | Active Codex checkpoint message delta gate (default: `20`) | `20` |
 | `AQUIFER_CODEX_CHECKPOINT_EVERY_USER_MESSAGES` | No | Optional user-message delta gate | `10` |
@@ -205,7 +267,7 @@ The script is idempotent (`WHERE canonical_key_v2 IS NULL` guard) and race-safe
 
 ## Host Integration
 
-MCP is the primary integration surface. Agent hosts connect to the Aquifer MCP server, which exposes eight tools: `session_recall`, `evidence_recall`, `session_feedback`, `memory_feedback`, `feedback_stats`, `session_bootstrap`, `memory_stats`, `memory_pending`.
+MCP is the primary integration surface. Agent hosts connect to the Aquifer MCP server, which exposes ten tools: `memory_recall`, `historical_recall`, `session_recall`, `evidence_recall`, `session_feedback`, `memory_feedback`, `memory_stats`, `memory_pending`, `feedback_stats`, `session_bootstrap`.
 
 | Integration | Route | Status | When to use |
 |-------------|-------|--------|-------------|
@@ -236,7 +298,7 @@ Add to your project's `.claude.json` or user-level MCP config:
 }
 ```
 
-Tools appear as `mcp__aquifer__session_recall`, `mcp__aquifer__evidence_recall`, `mcp__aquifer__session_bootstrap`, `mcp__aquifer__session_feedback`, `mcp__aquifer__memory_feedback`, `mcp__aquifer__feedback_stats`, `mcp__aquifer__memory_stats`, `mcp__aquifer__memory_pending`.
+Tools appear as `mcp__aquifer__memory_recall`, `mcp__aquifer__historical_recall`, `mcp__aquifer__session_recall`, `mcp__aquifer__evidence_recall`, `mcp__aquifer__session_feedback`, `mcp__aquifer__memory_feedback`, `mcp__aquifer__memory_stats`, `mcp__aquifer__memory_pending`, `mcp__aquifer__feedback_stats`, `mcp__aquifer__session_bootstrap`.
 
 For Codex long sessions, Aquifer exposes a UserPromptSubmit-friendly heartbeat
 command instead of installing a daemon:
@@ -287,27 +349,21 @@ the heartbeat hook is present.
 
 ### OpenClaw
 
-Add to `openclaw.json` under `mcp.servers`:
+Install or update Aquifer inside the OpenClaw host root, then let the installer
+wire both the MCP server and the optional extension from the same package root:
 
-```json
-{
-  "mcp": {
-    "servers": {
-      "aquifer": {
-        "command": "node",
-        "args": ["/path/to/aquifer/consumers/mcp.js"],
-        "env": {
-          "DATABASE_URL": "postgresql://...",
-          "AQUIFER_EMBED_BASE_URL": "http://localhost:11434/v1",
-          "AQUIFER_EMBED_MODEL": "bge-m3"
-        }
-      }
-    }
-  }
-}
+```bash
+npm install --prefix "$OPENCLAW_HOME" @shadowforge0/aquifer-memory@latest
+node "$OPENCLAW_HOME/node_modules/@shadowforge0/aquifer-memory/consumers/cli.js" install-openclaw --openclaw-home "$OPENCLAW_HOME"
 ```
 
-Tools materialize as `aquifer__session_recall`, `aquifer__evidence_recall`, `aquifer__session_feedback`, `aquifer__memory_feedback`, `aquifer__feedback_stats`, `aquifer__session_bootstrap`, `aquifer__memory_stats`, `aquifer__memory_pending` (server name prefix added by the host).
+The installer enables `plugins.entries["aquifer-memory"]`, adds the extension
+to `plugins.load.paths`, preserves existing `mcp.servers.aquifer.env` values,
+and backs up `openclaw.json` before writing. Use `--dry-run --json` to inspect
+package version, plugin config, MCP target, and extension link without changing
+files.
+
+Tools materialize as `aquifer__memory_recall`, `aquifer__historical_recall`, `aquifer__session_recall`, `aquifer__evidence_recall`, `aquifer__session_feedback`, `aquifer__memory_feedback`, `aquifer__memory_stats`, `aquifer__memory_pending`, `aquifer__feedback_stats`, `aquifer__session_bootstrap` (server name prefix added by the host).
 
 The OpenClaw plugin (`consumers/openclaw-plugin.js`) is retained for session capture via `before_reset` but is **not** the recommended tool delivery path. Use MCP.
 
@@ -722,7 +778,7 @@ Key indexes: `idx_insights_canonical_v2_active` (partial on active rows with can
 
 **Recall returns no results** — Make sure you've run `enrich` after `commit`. Raw sessions are not searchable until enriched (summarized + embedded). Check `aquifer stats` to see if summaries and turn embeddings exist.
 
-**OpenClaw tools not visible** — Use `mcp.servers.aquifer` in `openclaw.json`, not the plugin. Tools appear as `aquifer__session_recall` etc. The plugin (`consumers/openclaw-plugin.js`) is for session capture only.
+**OpenClaw tools not visible** — Use `mcp.servers.aquifer` in `openclaw.json`, not the plugin. Tools appear as `aquifer__memory_recall`, `aquifer__historical_recall`, `aquifer__session_recall`, etc. The plugin (`consumers/openclaw-plugin.js`) is for session capture only.
 
 **Embedding provider connection refused** — Verify your `AQUIFER_EMBED_BASE_URL` is reachable. For local Ollama, make sure the server is running and the model is pulled (`ollama pull bge-m3`).
 

package/README_CN.md

@@ -109,24 +109,40 @@ Claude Code、Claude Desktop 或任何支持 MCP 的 client——放进 `.mcp.js
 
 或直接跑：`DATABASE_URL=... EMBED_PROVIDER=ollama npx aquifer mcp`。（MCP server 本身对 env 严格——`quickstart` 的 autodetect 是试用路径，不是 production 路径。）
 
-第一轮 rollout 先保持 `AQUIFER_MEMORY_SERVING_MODE=legacy`。只有在你要让 `session_recall` 和 `session_bootstrap` 提供 active curated memory 时，才切到 `curated`；`evidence_recall` 会保留为显式 audit/debug 路径。要 rollback 只要把 env 或 config 切回 `legacy`。
+第一轮 rollout 先保持 `AQUIFER_MEMORY_SERVING_MODE=legacy`。只有在你要让兼容性 `session_recall` 和 `session_bootstrap` 提供 active curated memory 时，才切到 `curated`；`memory_recall` 是显式 current-memory lookup，`historical_recall` 是 historical/session 平面，`evidence_recall` 是 audit/debug 路径。要 rollback 只要把 env 或 config 切回 `legacy`。
 
 ### Common commands
 
 | Goal | Command |
 |---|---|
 | Verify setup | `npx aquifer quickstart` |
+| Run read-only diagnostics | `npx aquifer doctor --json` |
 | Start the MCP server | `npx aquifer mcp` |
 | Search memory manually | `npx aquifer recall "auth middleware"` |
+| Explain current-memory selection | `npx aquifer explain bootstrap --active-scope-key project:aquifer --json` |
+| Review current-memory feedback issues | `npx aquifer review queue --scope-key project:aquifer --json` |
+| Resolve a reviewed memory queue item | `npx aquifer review resolve --memory-id 42 --resolution resolved --reason "verified current" --expected-latest-issue-feedback-id 9 --json` |
 | Plan curated memory compaction | `npx aquifer compact --cadence daily --period-start 2026-04-27T00:00:00Z --period-end 2026-04-28T00:00:00Z` |
 | Generate a timer synthesis prompt | `npx aquifer operator compaction daily --include-synthesis-prompt --json` |
 | Apply reviewed timer synthesis candidates | `npx aquifer operator compaction daily --synthesis-summary-file /tmp/timer-summary.json --apply --promote-candidates --json` |
-| Inspect storage health | `npx aquifer stats` |
+| Inspect pending Codex checkpoint spool files | `npx aquifer codex-recovery checkpoint-spool-status --json --limit 10` |
+| Check memory readiness | `npx aquifer stats` |
+| Check saved-content preparation | `npx aquifer backlog --json` |
+| Dry-run a saved-content policy decision | `npx aquifer backlog --plan skip --status pending --source openclaw-mcp` |
 | Enrich pending sessions | `npx aquifer backfill` |
 
+`stats`, `backlog`, MCP `memory_stats`, and MCP `memory_pending` default to the
+same public status surface: `Aquifer status` or `Saved content status`, plus
+`Available`, `Attention`, and `Action` where relevant. Use CLI `--diagnostics`
+or MCP `diagnostics: true` when a host needs raw counters, buckets, guidance,
+or samples.
+
 Timer synthesis output is candidate material until an operator applies it with
 `--promote-candidates`; it does not become active curated memory from the
 prompt or summary file alone.
+`codex-recovery checkpoint-spool-status --json` reports local spool file
+metadata such as session, coverage, byte size, and modified time without
+printing checkpoint prompt text.
 
 需要 LLM 摘要、知识图谱、OpenAI embedding 或 reranker？往下看 [环境变量](#环境变量) 和 [docs/setup.md](docs/setup.md)。
 
@@ -194,7 +210,7 @@ const results = await aquifer.recall('auth middleware 决定', {
 
 ## 宿主集成
 
-MCP 是主要的集成接口。Agent 宿主连接到 Aquifer MCP server，该 server 暴露八个工具：`session_recall`、`evidence_recall`、`session_feedback`、`memory_feedback`、`feedback_stats`、`session_bootstrap`、`memory_stats`、`memory_pending`。
+MCP 是主要的集成接口。Agent 宿主连接到 Aquifer MCP server，该 server 暴露十个工具：`memory_recall`、`historical_recall`、`session_recall`、`evidence_recall`、`session_feedback`、`memory_feedback`、`memory_stats`、`memory_pending`、`feedback_stats`、`session_bootstrap`。
 
 | 集成方式 | 路径 | 状态 | 使用场景 |
 |----------|------|------|----------|
@@ -225,31 +241,25 @@ MCP 是主要的集成接口。Agent 宿主连接到 Aquifer MCP server，该 se
 }
 ```
 
-工具在 Claude Code 中显示为 `mcp__aquifer__session_recall`、`mcp__aquifer__evidence_recall`、`mcp__aquifer__session_bootstrap`、`mcp__aquifer__session_feedback`、`mcp__aquifer__memory_feedback`、`mcp__aquifer__feedback_stats`、`mcp__aquifer__memory_stats`、`mcp__aquifer__memory_pending`。
+工具在 Claude Code 中显示为 `mcp__aquifer__memory_recall`、`mcp__aquifer__historical_recall`、`mcp__aquifer__session_recall`、`mcp__aquifer__evidence_recall`、`mcp__aquifer__session_feedback`、`mcp__aquifer__memory_feedback`、`mcp__aquifer__memory_stats`、`mcp__aquifer__memory_pending`、`mcp__aquifer__feedback_stats`、`mcp__aquifer__session_bootstrap`。
 
 ### OpenClaw
 
-添加到 `openclaw.json` 的 `mcp.servers` 下：
+Install or update Aquifer inside the OpenClaw host root, then let the installer
+wire both the MCP server and the optional extension from the same package root:
 
-```json
-{
-  "mcp": {
-    "servers": {
-      "aquifer": {
-        "command": "node",
-        "args": ["/path/to/aquifer/consumers/mcp.js"],
-        "env": {
-          "DATABASE_URL": "postgresql://...",
-          "AQUIFER_EMBED_BASE_URL": "http://localhost:11434/v1",
-          "AQUIFER_EMBED_MODEL": "bge-m3"
-        }
-      }
-    }
-  }
-}
+```bash
+npm install --prefix "$OPENCLAW_HOME" @shadowforge0/aquifer-memory@latest
+node "$OPENCLAW_HOME/node_modules/@shadowforge0/aquifer-memory/consumers/cli.js" install-openclaw --openclaw-home "$OPENCLAW_HOME"
 ```
 
-工具显示为 `aquifer__session_recall`、`aquifer__evidence_recall`、`aquifer__session_feedback`、`aquifer__memory_feedback`、`aquifer__feedback_stats`、`aquifer__session_bootstrap`、`aquifer__memory_stats`、`aquifer__memory_pending`（宿主自动添加 server 名称前缀）。
+The installer enables `plugins.entries["aquifer-memory"]`, adds the extension
+to `plugins.load.paths`, preserves existing `mcp.servers.aquifer.env` values,
+and backs up `openclaw.json` before writing. Use `--dry-run --json` to inspect
+package version, plugin config, MCP target, and extension link without changing
+files.
+
+工具显示为 `aquifer__memory_recall`、`aquifer__historical_recall`、`aquifer__session_recall`、`aquifer__evidence_recall`、`aquifer__session_feedback`、`aquifer__memory_feedback`、`aquifer__memory_stats`、`aquifer__memory_pending`、`aquifer__feedback_stats`、`aquifer__session_bootstrap`（宿主自动添加 server 名称前缀）。
 
 OpenClaw 插件（`consumers/openclaw-plugin.js`）保留用于通过 `before_reset` 捕获 session，但**不是**推荐的工具分发路径。请使用 MCP。
 
@@ -649,7 +659,7 @@ opt-in pipeline（`createAquifer({stateChanges: {enabled, whitelist, confidenceT
 
 **Recall 没有返回结果** — 确保在 `commit` 之后执行了 `enrich`。原始 session 在丰富化（摘要 + embedding）之前不可搜索。运行 `aquifer stats` 检查摘要和 turn embedding 是否存在。
 
-**OpenClaw 工具不可见** — 在 `openclaw.json` 中使用 `mcp.servers.aquifer`，不要用插件。工具显示为 `aquifer__session_recall` 等。插件（`consumers/openclaw-plugin.js`）仅用于 session 捕获。
+**OpenClaw 工具不可见** — 在 `openclaw.json` 中使用 `mcp.servers.aquifer`，不要用插件。工具显示为 `aquifer__memory_recall`、`aquifer__historical_recall`、`aquifer__session_recall` 等。插件（`consumers/openclaw-plugin.js`）仅用于 session 捕获。
 
 **Embedding 提供商连接被拒** — 检查 `AQUIFER_EMBED_BASE_URL` 是否可达。本地 Ollama 需确保服务正在运行且模型已拉取（`ollama pull bge-m3`）。
 

package/README_TW.md

@@ -67,22 +67,33 @@ Claude Code、Claude Desktop 或任何支援 MCP 的 client——放進 `.mcp.js
 
 或直接跑：`DATABASE_URL=... EMBED_PROVIDER=ollama npx aquifer mcp`。MCP server 本身對 env 比較嚴格，`quickstart` 的 autodetect 是試用路徑，不是 production 路徑。
 
-第一輪 rollout 先維持 `AQUIFER_MEMORY_SERVING_MODE=legacy`。只有在你要讓 `session_recall` 跟 `session_bootstrap` 提供 active curated memory 時，才切到 `curated`；`evidence_recall` 會保留為顯式 audit/debug 路徑。要 rollback 只要把 env 或 config 切回 `legacy`。
+第一輪 rollout 先維持 `AQUIFER_MEMORY_SERVING_MODE=legacy`。只有在你要讓相容性 `session_recall` 跟 `session_bootstrap` 提供 active curated memory 時，才切到 `curated`；`memory_recall` 是顯式 current-memory lookup，`historical_recall` 是 historical/session 平面，`evidence_recall` 是 audit/debug 路徑。要 rollback 只要把 env 或 config 切回 `legacy`。
+
+Curated serving 受 scope 邊界保護。`AQUIFER_MEMORY_ACTIVE_SCOPE_PATH` 是 inheritance 的順序路徑，`AQUIFER_MEMORY_ALLOWED_SCOPE_KEYS` 是 caller boundary。若沒有設定 `activeScopePath`，Aquifer 會預設使用 `global` 加上 configured `activeScopeKey`；沒有 active scope 時則只用 `global`。若沒有設定 `allowedScopeKeys`，Aquifer 會預設使用該 active scope path；runtime request 超出這個邊界時，會在讀 current memory rows 前直接拒絕。
 
 ### 常用指令
 
 | 目標 | 指令 |
 |---|---|
 | 驗證 setup | `npx aquifer quickstart` |
+| 執行唯讀治理診斷 | `npx aquifer doctor --json` |
 | 啟動 MCP server | `npx aquifer mcp` |
 | 手動查記憶 | `npx aquifer recall "auth middleware"` |
+| 解釋 current-memory 選取 | `npx aquifer explain bootstrap --active-scope-key project:aquifer --json` |
+| 檢查 current-memory feedback issue | `npx aquifer review queue --scope-key project:aquifer --json` |
+| 關閉已人工審查的記憶 queue item | `npx aquifer review resolve --memory-id 42 --resolution resolved --reason "verified current" --expected-latest-issue-feedback-id 9 --json` |
 | 規劃 curated memory 壓縮 | `npx aquifer compact --cadence daily --period-start 2026-04-27T00:00:00Z --period-end 2026-04-28T00:00:00Z` |
 | 產生 timer synthesis prompt | `npx aquifer operator compaction daily --include-synthesis-prompt --json` |
 | 套用已審核的 timer synthesis candidates | `npx aquifer operator compaction daily --synthesis-summary-file /tmp/timer-summary.json --apply --promote-candidates --json` |
-| 看儲存狀態 | `npx aquifer stats` |
-| 補跑 pending session | `npx aquifer backfill` |
+| 檢查 Codex checkpoint spool 待處理檔 | `npx aquifer codex-recovery checkpoint-spool-status --json --limit 10` |
+| 看記憶是否可用 | `npx aquifer stats` |
+| 檢查已儲存內容準備狀態 | `npx aquifer backlog --json` |
+| 準備已儲存內容 | `npx aquifer backfill` |
+
+`stats`、`backlog`、MCP `memory_stats`、MCP `memory_pending` 預設共用同一個 public status surface：`Aquifer status` 或 `Saved content status`，必要時再加 `Available`、`Attention`、`Action`。需要 raw counters、source / agent / status 分桶、guidance 或 samples 時，CLI 用 `--diagnostics`，MCP 傳 `diagnostics: true`。
 
 Timer synthesis output 在 operator 用 `--promote-candidates` apply 前都只是 candidate material；光有 prompt 或 summary file 不會變成 active curated memory。
+`codex-recovery checkpoint-spool-status --json` 只列出本機 spool 檔的 session、coverage、大小與修改時間，不會印出 checkpoint prompt 內容。
 
 需要 LLM 摘要、知識圖譜、OpenAI embedding、reranker 或維運細節，就往下看 [環境變數](#環境變數) 跟 [docs/setup.md](docs/setup.md)。
 
@@ -194,7 +205,7 @@ const results = await aquifer.recall('auth middleware 決定', {
 
 ## 主機整合（Host Integration）
 
-MCP 是主要的整合介面。Agent 主機連接 Aquifer MCP 伺服器，伺服器提供八個工具：`session_recall`、`evidence_recall`、`session_feedback`、`memory_feedback`、`feedback_stats`、`session_bootstrap`、`memory_stats`、`memory_pending`。
+MCP 是主要的整合介面。Agent 主機連接 Aquifer MCP 伺服器，伺服器提供十個工具：`memory_recall`、`historical_recall`、`session_recall`、`evidence_recall`、`session_feedback`、`memory_feedback`、`memory_stats`、`memory_pending`、`feedback_stats`、`session_bootstrap`。
 
 | 整合方式 | 路由 | 狀態 | 使用時機 |
 |----------|------|------|----------|
@@ -225,31 +236,20 @@ MCP 是主要的整合介面。Agent 主機連接 Aquifer MCP 伺服器，伺服
 }
 ```
 
-工具會以 `mcp__aquifer__session_recall`、`mcp__aquifer__evidence_recall`、`mcp__aquifer__session_bootstrap`、`mcp__aquifer__session_feedback`、`mcp__aquifer__memory_feedback`、`mcp__aquifer__feedback_stats`、`mcp__aquifer__memory_stats`、`mcp__aquifer__memory_pending` 等名稱出現。
+工具會以 `mcp__aquifer__memory_recall`、`mcp__aquifer__historical_recall`、`mcp__aquifer__session_recall`、`mcp__aquifer__evidence_recall`、`mcp__aquifer__session_feedback`、`mcp__aquifer__memory_feedback`、`mcp__aquifer__memory_stats`、`mcp__aquifer__memory_pending`、`mcp__aquifer__feedback_stats`、`mcp__aquifer__session_bootstrap` 等名稱出現。
 
 ### OpenClaw
 
-加入 `openclaw.json` 的 `mcp.servers` 區段：
+先把 Aquifer 安裝或更新到 OpenClaw host root，再讓 installer 從同一個 package root 接好 MCP server 與可選的 extension：
 
-```json
-{
-  "mcp": {
-    "servers": {
-      "aquifer": {
-        "command": "node",
-        "args": ["/path/to/aquifer/consumers/mcp.js"],
-        "env": {
-          "DATABASE_URL": "postgresql://...",
-          "AQUIFER_EMBED_BASE_URL": "http://localhost:11434/v1",
-          "AQUIFER_EMBED_MODEL": "bge-m3"
-        }
-      }
-    }
-  }
-}
+```bash
+npm install --prefix "$OPENCLAW_HOME" @shadowforge0/aquifer-memory@latest
+node "$OPENCLAW_HOME/node_modules/@shadowforge0/aquifer-memory/consumers/cli.js" install-openclaw --openclaw-home "$OPENCLAW_HOME"
 ```
 
-工具會以 `aquifer__session_recall`、`aquifer__evidence_recall`、`aquifer__session_feedback`、`aquifer__memory_feedback`、`aquifer__feedback_stats`、`aquifer__session_bootstrap`、`aquifer__memory_stats`、`aquifer__memory_pending` 等名稱出現（主機自動加上伺服器名稱前綴）。
+installer 會啟用 `plugins.entries["aquifer-memory"]`、把 extension 加進 `plugins.load.paths`、保留既有 `mcp.servers.aquifer.env`，並在寫入前備份 `openclaw.json`。可用 `--dry-run --json` 檢查 package 版本、plugin config、MCP 目標與 extension link，不改檔案。
+
+工具會以 `aquifer__memory_recall`、`aquifer__historical_recall`、`aquifer__session_recall`、`aquifer__evidence_recall`、`aquifer__session_feedback`、`aquifer__memory_feedback`、`aquifer__memory_stats`、`aquifer__memory_pending`、`aquifer__feedback_stats`、`aquifer__session_bootstrap` 等名稱出現（主機自動加上伺服器名稱前綴）。
 
 OpenClaw plugin（`consumers/openclaw-plugin.js`）保留用於 `before_reset` session 擷取，但**不是**建議的工具傳遞方式。請用 MCP。
 
@@ -282,6 +282,7 @@ OpenClaw plugin（`consumers/openclaw-plugin.js`）保留用於 `before_reset` s
 | `AQUIFER_MEMORY_SERVING_MODE` | 否 | 對外 serving mode：預設 `legacy`，可 opt-in `curated` | `curated` |
 | `AQUIFER_MEMORY_ACTIVE_SCOPE_KEY` | 否 | recall/bootstrap 預設 active curated scope | `project:aquifer` |
 | `AQUIFER_MEMORY_ACTIVE_SCOPE_PATH` | 否 | curated scope inheritance 的順序路徑 | `global,project:aquifer` |
+| `AQUIFER_MEMORY_ALLOWED_SCOPE_KEYS` | 否 | curated scope request 的 caller boundary，預設為 configured active scope path | `global,project:aquifer` |
 | `AQUIFER_MIGRATIONS_MODE` | 否 | 啟動 handshake 模式：`apply`（預設）、`check`、`off` | `apply` |
 | `AQUIFER_MIGRATION_LOCK_TIMEOUT_MS` | 否 | advisory lock 等待上限，逾時拋 `AQ_MIGRATION_LOCK_TIMEOUT`（預設 30000） | `30000` |
 | `AQUIFER_INSIGHTS_DEDUP_MODE` | 否 | insights 語意去重模式：`off`（預設）、`shadow`、`enforce`——此欄位 env 蓋過程式碼設定，讓 operator 不用重部署就能緊急關閉 | `shadow` |
@@ -657,7 +658,7 @@ opt-in pipeline（`createAquifer({stateChanges: {enabled, whitelist, confidenceT
 
 **Recall 沒有回傳結果** — 確認你在 `commit` 之後有執行 `enrich`。未豐富化的 session 無法被搜尋（需要摘要 + embedding）。用 `aquifer stats` 檢查摘要和 turn embedding 是否存在。
 
-**OpenClaw 看不到工具** — 請在 `openclaw.json` 使用 `mcp.servers.aquifer`，不要用 plugin。工具會以 `aquifer__session_recall` 等名稱出現。Plugin（`consumers/openclaw-plugin.js`）僅用於 session 擷取。
+**OpenClaw 看不到工具** — 請在 `openclaw.json` 使用 `mcp.servers.aquifer`，不要用 plugin。工具會以 `aquifer__memory_recall`、`aquifer__historical_recall`、`aquifer__session_recall` 等名稱出現。Plugin（`consumers/openclaw-plugin.js`）僅用於 session 擷取。
 
 **Embedding 供應商連線被拒** — 確認 `AQUIFER_EMBED_BASE_URL` 可以連通。若使用本地 Ollama，確保伺服器正在執行且模型已下載（`ollama pull bge-m3`）。
 

package/aquifer.config.example.json

@@ -22,7 +22,8 @@
   "memory": {
     "servingMode": "legacy",
     "activeScopeKey": null,
-    "activeScopePath": null
+    "activeScopePath": null,
+    "allowedScopeKeys": null
   },
   "codex": {
     "checkpoint": {