agent-recall-mcp 3.4.19 → 3.4.21

package/README.md

@@ -1,366 +1,238 @@
 <h1 align="center">AgentRecall</h1>
 
 <p align="center"><strong>Your agent doesn't just remember. It learns how you think.</strong></p>
-<p align="center">Every correction saved is a mistake never repeated. Every insight compounded is tokens never wasted rebuilding context.</p>
+<p align="center"><strong>你的 agent 不只是记得。它在学你怎么想。</strong></p>
+<p align="center">Every correction saved is a mistake never repeated. Every insight compounded is tokens never wasted rebuilding context.<br/>每一次纠正都是不会重复的错误。每一次复合都是不会重建的上下文。</p>
 <p align="center">Persistent, compounding memory + automatic correction capture. MCP server + SDK + CLI.</p>
 
 <p align="center">
+  <a href="https://t.me/+ywZwoHrg3AM0NDVi"><img src="https://img.shields.io/badge/Telegram-Community-2CA5E0?style=flat-square&logo=telegram" alt="Telegram Community"></a>
   <a href="https://www.npmjs.com/package/agent-recall-mcp"><img src="https://img.shields.io/npm/v/agent-recall-mcp?style=flat-square&label=MCP&color=5D34F2" alt="MCP npm"></a>
   <a href="https://www.npmjs.com/package/agent-recall-sdk"><img src="https://img.shields.io/npm/v/agent-recall-sdk?style=flat-square&label=SDK&color=0EA5E9" alt="SDK npm"></a>
   <a href="https://www.npmjs.com/package/agent-recall-cli"><img src="https://img.shields.io/npm/v/agent-recall-cli?style=flat-square&label=CLI&color=10B981" alt="CLI npm"></a>
   <a href="https://github.com/Goldentrii/AgentRecall/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-brightgreen?style=flat-square" alt="License"></a>
   <a href="https://lobehub.com/mcp/goldentrii-agentrecall"><img src="https://lobehub.com/badge/mcp/goldentrii-agentrecall" alt="MCP Badge"></a>
-  <img src="https://img.shields.io/badge/MCP-10_tools-orange?style=flat-square" alt="Tools">
+  <img src="https://img.shields.io/badge/MCP-18_tools-orange?style=flat-square" alt="Tools">
+  <img src="https://img.shields.io/badge/memory_layers-5-7C3AED?style=flat-square" alt="5 layers">
   <img src="https://img.shields.io/badge/cloud-zero-blue?style=flat-square" alt="Zero Cloud">
   <img src="https://img.shields.io/badge/Obsidian-compatible-7C3AED?style=flat-square" alt="Obsidian">
-  <img src="https://img.shields.io/badge/digest_cache-83%25_token_savings-FF6B6B?style=flat-square" alt="Digest cache savings">
-  <img src="https://img.shields.io/badge/saves_up_to-57%25_tokens-FF6B6B?style=flat-square" alt="Token savings">
-  <img src="https://img.shields.io/badge/break--even-3--4_sessions-22C55E?style=flat-square" alt="Break-even">
-  <img src="https://img.shields.io/badge/scoring-RRF_(Cormack_2009)-7C3AED?style=flat-square" alt="RRF scoring">
-  <img src="https://img.shields.io/badge/decay-Ebbinghaus%2BZipf-3B82F6?style=flat-square" alt="Ebbinghaus+Zipf decay">
-  <img src="https://img.shields.io/badge/feedback-Bayesian_Beta_(active)-F59E0B?style=flat-square" alt="Beta distribution">
-  <img src="https://img.shields.io/badge/semantic_recall-pgvector_%2B_RRF-8B5CF6?style=flat-square" alt="Semantic recall">
+  <img src="https://img.shields.io/badge/decay-FSRS--lite-3B82F6?style=flat-square" alt="FSRS-lite decay">
+  <img src="https://img.shields.io/badge/retrieval-Hopfield_%2B_RRF-8B5CF6?style=flat-square" alt="Hopfield retrieval">
+  <img src="https://img.shields.io/badge/feedback-precision_KPI-F59E0B?style=flat-square" alt="Precision KPI">
 </p>
 
 <p align="center">
   <b>EN:</b>&nbsp;
-  <a href="#why-choose-agentrecall">Why</a> ·
-  <a href="#three-ways-to-use-it">Use</a> ·
-  <a href="#quick-start">Install</a> ·
-  <a href="#semantic-recall--pgvector-backend-v340">Semantic Recall</a> ·
-  <a href="#10-mcp-tools">Tools</a> ·
-  <a href="#how-memory-compounds">Compounding</a> ·
+  <a href="#what-why--什么和为什么">Why</a> ·
+  <a href="#5-memory-layers--五层记忆模型">Memory</a> ·
+  <a href="#quick-start--快速开始">Install</a> ·
+  <a href="#18-mcp-tools--18-个-mcp-工具">Tools</a> ·
+  <a href="#how-memory-compounds--记忆如何复合">Compounding</a> ·
+  <a href="#whats-new-in-phase-6--phase-6-新增">Phase 6</a> ·
   <a href="#sdk-api">SDK</a> ·
-  <a href="#architecture">Architecture</a> ·
-  <a href="#docs">Docs</a>
+  <a href="#cli">CLI</a> ·
+  <a href="#architecture--架构">Arch</a>
   &nbsp;&nbsp;|&nbsp;&nbsp;
   <b>中文:</b>&nbsp;
-  <a href="#agentrecall中文文档">简介</a> ·
-  <a href="#快速开始">安装</a> ·
-  <a href="#语义召回--pgvector-v340">语义召回</a> ·
-  <a href="#10-个-mcp-工具">工具</a> ·
-  <a href="#记忆如何复合增长">复合</a> ·
-  <a href="#架构">架构</a>
+  <a href="#what-why--什么和为什么">什么</a> ·
+  <a href="#5-memory-layers--五层记忆模型">记忆模型</a> ·
+  <a href="#quick-start--快速开始">安装</a> ·
+  <a href="#18-mcp-tools--18-个-mcp-工具">工具</a> ·
+  <a href="#how-memory-compounds--记忆如何复合">复合</a> ·
+  <a href="#whats-new-in-phase-6--phase-6-新增">新增</a>
 </p>
 
 ---
 
 <p align="center">
-  <a href="#arstatus-arsave-arstart-arsaveall-and-arbootstrap"><img src="https://img.shields.io/badge/%2Farstatus-START_HERE-22C55E?style=for-the-badge" alt="/arstatus"></a>
-  <a href="#arstatus-arsave-arstart-arsaveall-and-arbootstrap"><img src="https://img.shields.io/badge/%2Farstart-Load_Context-4ECDC4?style=for-the-badge" alt="/arstart"></a>
-  <a href="#arstatus-arsave-arstart-arsaveall-and-arbootstrap"><img src="https://img.shields.io/badge/%2Farsave-Save_Session-FF6B6B?style=for-the-badge" alt="/arsave"></a>
-  <a href="#arstatus-arsave-arstart-arsaveall-and-arbootstrap"><img src="https://img.shields.io/badge/%2Farsaveall-Batch_Save_All-FFD93D?style=for-the-badge" alt="/arsaveall"></a>
-  <a href="#already-using-another-memory-system-arbootstrap"><img src="https://img.shields.io/badge/%2Farbootstrap-Transfer_Memory-8B5CF6?style=for-the-badge" alt="/arbootstrap"></a>
+  <a href="#the-session-loop--会话循环"><img src="https://img.shields.io/badge/%2Farstatus-START_HERE-22C55E?style=for-the-badge" alt="/arstatus"></a>
+  <a href="#the-session-loop--会话循环"><img src="https://img.shields.io/badge/%2Farstart-Load_Context-4ECDC4?style=for-the-badge" alt="/arstart"></a>
+  <a href="#the-session-loop--会话循环"><img src="https://img.shields.io/badge/%2Farsave-Save_Session-FF6B6B?style=for-the-badge" alt="/arsave"></a>
+  <a href="#the-session-loop--会话循环"><img src="https://img.shields.io/badge/%2Farsaveall-Batch_Save-FFD93D?style=for-the-badge" alt="/arsaveall"></a>
+  <a href="#already-using-another-memory-system--已经用过别的"><img src="https://img.shields.io/badge/%2Farbootstrap-Transfer_Memory-8B5CF6?style=for-the-badge" alt="/arbootstrap"></a>
 </p>
-<p align="center">
-  <img src="https://img.shields.io/badge/AUTO-hook--start-8B5CF6?style=for-the-badge" alt="hook-start">
-  <img src="https://img.shields.io/badge/AUTO-hook--correction-F97316?style=for-the-badge" alt="hook-correction">
-  <img src="https://img.shields.io/badge/AUTO-hook--end-06B6D4?style=for-the-badge" alt="hook-end">
-</p>
-<p align="center">
-  <a href="#how-memory-compounds"><img src="https://img.shields.io/badge/1-AUTO--NAMING-5D34F2?style=for-the-badge" alt="Auto-Naming"></a>
-  <a href="#how-memory-compounds"><img src="https://img.shields.io/badge/2-INDEXES-0EA5E9?style=for-the-badge" alt="Indexes"></a>
-  <a href="#how-memory-compounds"><img src="https://img.shields.io/badge/3-RELATIVITY-10B981?style=for-the-badge" alt="Relativity"></a>
-  <a href="#how-memory-compounds"><img src="https://img.shields.io/badge/4-WEIGHT_%2B_DECAY-F59E0B?style=for-the-badge" alt="Weight + Decay"></a>
-  <a href="#how-memory-compounds"><img src="https://img.shields.io/badge/5-FEEDBACK_LOOP-EF4444?style=for-the-badge" alt="Feedback Loop"></a>
-</p>
-
-## Already Using Another Memory System? `/arbootstrap`
-
-> [!NOTE]
-> **You don't start from zero.** If you've been using Claude's built-in memory, Mem0, or just working in git repos — AgentRecall can discover and import your existing context automatically.
-
-Most users installing AgentRecall aren't starting fresh. They already have:
-- **Git repos** with months of commit history and project structure
-- **Claude AutoMemory** (`~/.claude/projects/`) with user profiles, feedback, and project memories
-- **CLAUDE.md files** with project conventions and architecture decisions
-
-**`/arbootstrap`** scans your machine and imports everything in one shot:
-
-```
-/arbootstrap
-
-──────────────────────────────────────────────────────────────
-  AgentRecall  Bootstrap Scan          2026-04-26
-──────────────────────────────────────────────────────────────
-
-  Found on your machine:
-      24 git repos
-      92 Claude memory files
-       3 CLAUDE.md files
-
-  Projects:
-      18 new (not yet in AgentRecall)
-      10 already imported
-
-  Scan time: 141ms
-──────────────────────────────────────────────────────────────
-```
-
-**What gets imported per project:**
-- **Identity** — project name, language, description → `palace/identity.md`
-- **Architecture** — CLAUDE.md conventions → `palace/rooms/architecture/`
-- **Memory** — Claude AutoMemory files → `palace/rooms/knowledge/`
-- **Trajectory** — recent git history → initial journal entry
-
-**Safety guarantees:**
-- Scan is read-only — never writes to your machine
-- Import only writes to `~/.agent-recall/` — never modifies source files
-- Skips `.env`, credentials, `.pem`, `.key` — never reads secrets
-- Projects already in AgentRecall are skipped (no double-import)
-
-**For MCP-only environments** (Codex, Cursor, VS Code Copilot):
-```
-bootstrap_scan()                    # discover what's on the machine
-bootstrap_import({ scan_result })   # import selected projects
-```
-
-**For CLI:**
-```bash
-ar bootstrap                        # scan and show results
-ar bootstrap --dry-run              # preview what would be imported
-ar bootstrap --import               # import all new projects
-ar bootstrap --import --project X   # import one project
-```
-
-After bootstrap, run `/arstatus` — your projects are ready.
 
 ---
 
-## `/arstatus`, `/arsave`, `/arstart`, `/arsaveall`, and `/arbootstrap`
-
-> [!TIP]
-> **New to AgentRecall?** Read the **[→ Command Reference](docs/commands.md)** — full instructions, all example outputs, installation, and troubleshooting in one place.
-
-> [!IMPORTANT]
-> **Run `/arstatus` at the start of every session.** It shows all your projects, what's pending, what's blocked, and lets you pick what to work on — by number, not by remembering project names. Without it, a fresh agent has no idea where to begin.
-
-| Command | When | What it does |
-|---------|------|-------------|
-| ⭐ **`/arstatus`** | **Every session — run this first** | **Status board across ALL projects: pending work, blockers, numbered pick list. The true cold start.** |
-| **`/arstart`** | After picking a project | Load deep context for one project: palace rooms, corrections, task-specific recall |
-| **`/arsave`** | End of session | Write journal + consolidate to palace + update awareness |
-| **`/arsaveall`** | End of day (multi-session) | **Batch save all parallel sessions at once** — scan, merge, deduplicate, done |
-| **`/arbootstrap`** | **First install / switching from another memory system** | **Scan your machine for existing projects and import them into AgentRecall in seconds** |
-
-**The session flow:** `/arstatus` → pick a number → `/arstart <project>` → work → `/arsave`.
-
-**Running 5 agents in parallel?** Don't `/arsave` five times. Type **`/arsaveall`** once — it scans all of today's sessions across all projects, merges them into consolidated journals, deduplicates insights, and updates awareness in one shot. Each session writes to its own file (session-ID scoped), so **no conflicts, no data loss, no matter how many windows you have open.**
-
-### What You'll See
-
-Type `/arstatus` → see everything in flight across all projects, pick by number:
-
-```
-──────────────────────────────────────────────────────────────
-  AgentRecall  Status Board        2026-04-21    5 projects
-──────────────────────────────────────────────────────────────
-
-  1  ⚠ novada-site       2026-04-21   BLOCKED
-       Blocked: .env.local missing — Phase 1 cannot proceed
-
-  2  ● novada-mcp        2026-04-21
-       Next: fix novada_search POST /request → publish v0.8.0
-
-  3  ● prismma-scraper   2026-04-17
-       Next: UI upgrade Option A — light mode + 3D visuals
-
-  4  ✓ AgentRecall       2026-04-21   complete
-       Collecting real production data
+## What & Why · 什么和为什么
 
-──────────────────────────────────────────────────────────────
-  Enter a number, or:
-    N  New project (with memory — agent knows your full history)
-    X  New project (clean slate — no prior context, pure objectivity)
-──────────────────────────────────────────────────────────────
-```
-
-Type `/arsave` → the system saves everything and renders a card with exact file paths and counts:
-
-```
-──────────────────────────────────────────────────────────────
-  AgentRecall  ✓ Saved    my-project   2026-04-20   #12
-──────────────────────────────────────────────────────────────
-
-  Journal       ~/.agent-recall/projects/my-project/journal/
-                └─ 2026-04-20--arsave--15L--review-feedback.md    [written]
+<table>
+<tr>
+<th width="50%">🇬🇧 English</th>
+<th width="50%">🇨🇳 中文</th>
+</tr>
+<tr>
+<td>
 
-  Awareness     2 insights added  (8 total)
-
-  Palace        ~/.agent-recall/projects/my-project/palace/
-                ├─ rooms/Architecture       [updated]
-                └─ rooms/Goals              [updated]
-
-  Corrections   3 stored  (always loaded at session start)
-
-  ⚡ Similar entries found — consider merging:
-     2026-04-19  (review, feedback, architecture)
-
-──────────────────────────────────────────────────────────────
-```
-
-Type `/arstart` → loads all context from memory in one shot:
-
-```
-──────────────────────────────────────────────────────────────
-  AgentRecall  ↻ Loaded    my-project   2026-04-21
-──────────────────────────────────────────────────────────────
-
-  Project       my-project — SaaS platform for AI agents
-  Last session  2026-04-20 — review + feedback loop shipped
-
-  Insights (top 3):
-    [5×] Server-rendered cards beat agent templates
-    [3×] Per-message dedup beats per-session dedup
-    [2×] Stemming + synonyms improve keyword recall
-
-  ⚠ Past corrections — watch out:
-    - "No dark backgrounds" (corrected 3×)
-    - "Use bb-browser, not Playwright" (corrected 2×)
-
-  Cross-project: 2 related insights from novada-mcp
-
-──────────────────────────────────────────────────────────────
-```
-
-Type `/arsaveall` → batch-saves all parallel sessions at once:
-
-```
-──────────────────────────────────────────────────────────────
-  AgentRecall  ✓ Batch Saved    2026-04-20
-──────────────────────────────────────────────────────────────
-
-  Sessions scanned    5
-  Projects saved      my-project, novada-mcp, prismma-scraper
-  Insights merged     4 (deduplicated from 7)
-  Corrections         2 new (auto-captured via hooks)
-
-──────────────────────────────────────────────────────────────
-```
+**AgentRecall is not a memory tool. It's a learning loop.**
 
-Type `/arbootstrap` → discover and import projects from your existing tools:
+Memory is the mechanism. Understanding is the goal. Every time you correct your agent — *"no, not that version"*, *"put this section first"*, *"ask me before you assume"* — that correction is stored, weighted, and recalled next time.
 
-```
-──────────────────────────────────────────────────────────────
-  AgentRecall  Bootstrap Complete      2026-04-26
-──────────────────────────────────────────────────────────────
+After 10 sessions, your agent doesn't just remember your project. It understands how you think: your priorities, your communication style, your non-negotiables.
 
-  12 projects created
-  87 items imported (identity, memory, architecture, trajectory)
-   3 items skipped
-   0 errors
+</td>
+<td>
 
-  Run /arstatus to see your projects.
-──────────────────────────────────────────────────────────────
-```
+**AgentRecall 不是记忆工具，是学习闭环。**
 
-The cards are **rendered server-side** — computed from actual operation results, not agent interpretation. What you see is always accurate.
+记忆是机制，理解才是目标。每一次纠正——*"不是那个版本"*、*"先放这一段"*、*"假设之前先问我"*——都会被存储、加权、并在下次召回。
 
-```bash
-# Install commands (one-time, Claude Code only)
-mkdir -p ~/.claude/commands
-curl -o ~/.claude/commands/arstatus.md https://raw.githubusercontent.com/Goldentrii/AgentRecall/main/commands/arstatus.md
-curl -o ~/.claude/commands/arstart.md https://raw.githubusercontent.com/Goldentrii/AgentRecall/main/commands/arstart.md
-curl -o ~/.claude/commands/arsave.md https://raw.githubusercontent.com/Goldentrii/AgentRecall/main/commands/arsave.md
-curl -o ~/.claude/commands/arsaveall.md https://raw.githubusercontent.com/Goldentrii/AgentRecall/main/commands/arsaveall.md
-curl -o ~/.claude/commands/arbootstrap.md https://raw.githubusercontent.com/Goldentrii/AgentRecall/main/commands/arbootstrap.md
-```
+跑 10 次会话之后，agent 不只是记得项目，它理解你的思考方式：优先级、沟通风格、不可妥协的底线。
 
-### The Difference
+</td>
+</tr>
+<tr>
+<td>
 
-```
-WITHOUT AgentRecall                    WITH AgentRecall
-──────────────────                     ────────────────
-
-Day 1: Build monorepo                 Day 1: /arstart → /arsave
-Day 2: "What monorepo?"               Day 2: /arstart
-  → 20 min re-explaining                → 2 sec: loads all decisions
-  → Agent repeats same mistakes          → Knows "no version inflation"
-  → Forgets your priorities              → Knows "arsave = hero section"
-  → Misses half the tasks                → Pushes to both repos
-```
+**Five things that make it different:**
 
-```
-WITHOUT AgentRecall (5 parallel agents)      WITH AgentRecall (5 parallel agents)
-──────────────────────────────────────       ────────────────────────────────────
-
-Agent 1 finishes: you /arsave                Agent 1-5 finish: you type /arsaveall once
-Agent 2 finishes: you /arsave again            → Scans all 5 sessions automatically
-Agent 3 finishes: you /arsave again            → Merges into consolidated journals
-Agent 4 finishes: you /arsave again            → Deduplicates insights across sessions
-Agent 5 finishes: you /arsave again            → Zero conflicts (session-ID scoped files)
-  → 5x the work, corrections lost             → One command, everything saved
-  → Agent 3's correction unknown to Agent 5    → All agents share the same memory
-```
+- **Correction-first.** When you say "no, that's wrong", we log a `CorrectionRecord` with severity, holder, and evidence. After N confirmations across sessions, it auto-promotes to a cross-project insight.
+- **Measurable learning loop.** Every correction tracks `retrieved_count`, `heeded_count`, `recurrence_count`, `precision`. The KPI that matters: *did the same bug recur after we warned about it?*
+- **Five memory types.** Episodic, semantic, procedural, narrative, correction — mapped to canonical cognitive-psychology taxonomy (Squire 2004, Tulving 1972).
+- **Local markdown only.** Everything lives in `~/.agent-recall/`. Open it in Obsidian. Grep it in the terminal. Version it in git. No cloud, no API keys, no lock-in.
+- **Backed by published math.** FSRS-lite decay (Ebbinghaus → SuperMemo → FSRS-6), Modern Hopfield retrieval (Ramsauer 2020), RRF fusion (Cormack 2009).
 
-### Three Layers of Value
+</td>
+<td>
 
-**Layer 1 (5 seconds):** It makes your AI agent remember what happened last session.
+**让它不同的五件事：**
 
-**Layer 2 (30 seconds):** Every time you correct your agent — "no, not that version", "ask me first" — that correction is stored permanently and recalled before the agent makes the same mistake again. After 10 sessions, your agent understands your priorities, your communication style, your non-negotiables.
+- **以纠正为先。** 你说"不对"时，我们记下 `CorrectionRecord`（严重度、归属、证据）。跨会话被确认 N 次后，自动晋升为跨项目的 insight。
+- **可量化的学习闭环。** 每条纠正都跟踪 `retrieved_count`（被召回多少次）、`heeded_count`（被遵守多少次）、`recurrence_count`（同样的 bug 是否复发）、`precision`。唯一重要的 KPI：警告之后同样的 bug 还复发吗？
+- **五种记忆类型。** Episodic、semantic、procedural、narrative、correction —— 对应认知心理学经典分类（Squire 2004、Tulving 1972）。
+- **只用本地 markdown。** 一切都在 `~/.agent-recall/`。用 Obsidian 打开、用终端 grep、用 git 版本管理。零云、零 API key、零锁定。
+- **基于已发表数学。** FSRS-lite 衰减（Ebbinghaus → SuperMemo → FSRS-6）、Modern Hopfield 检索（Ramsauer 2020）、RRF 融合（Cormack 2009）。
 
-**Layer 3 (2 minutes):** The [Intelligent Distance Protocol](https://github.com/Goldentrii/AgentRecall/wiki/Intelligent-Distance). The structural gap between human thinking and AI action can't be closed — but it can be navigated better every session. Corrections are training data. The 200-line awareness cap forces quality over quantity. Cross-project insights mean lessons learned once apply everywhere.
+</td>
+</tr>
+</table>
 
 ---
 
-## Why Choose AgentRecall
-
-**AgentRecall is not a memory tool. It's a learning loop.**
-
-Memory is the mechanism. Understanding is the goal. Every time you correct your agent — "no, not that version", "put this section first", "ask me before you assume" — that correction is stored, weighted, and recalled next time. After 10 sessions, your agent doesn't just remember your project. It understands how you think: your priorities, your communication style, your non-negotiables.
+## 5 Memory Layers · 五层记忆模型
+
+The canonical cognitive-psychology taxonomy mapped to your agent's filesystem · 把认知心理学的经典记忆分类映射到你的文件系统：
+
+<table>
+<tr>
+<th>Layer · 层</th>
+<th>Type · 类型</th>
+<th>EN — What it holds</th>
+<th>中文 — 存什么</th>
+<th>Path</th>
+</tr>
+<tr>
+<td>1</td>
+<td><b>Episodic</b><br/>情景</td>
+<td>What happened in each session, chronologically. Auto-written by the agent during work.</td>
+<td>每次会话发生了什么，按时间顺序。Agent 工作时自动写入。</td>
+<td><code>journal/</code></td>
+</tr>
+<tr>
+<td>2</td>
+<td><b>Semantic</b><br/>语义</td>
+<td>Topic-clustered facts with <code>[[wikilinks]]</code>: Architecture, Goals, Blockers, etc.</td>
+<td>按主题聚类的事实，带 <code>[[wikilinks]]</code>：架构、目标、阻塞等。</td>
+<td><code>palace/rooms/</code></td>
+</tr>
+<tr>
+<td>3</td>
+<td><b>Procedural</b><br/>程序<br/><i>NEW</i></td>
+<td>IF-THEN production rules: <i>"When setting up Cloudflare DNS, do these 4 steps."</i> Reusable how-tos.</td>
+<td>IF-THEN 产生式规则："设置 Cloudflare DNS 时，按这 4 步走"。可复用的操作流程。</td>
+<td><code>palace/skills/</code></td>
+</tr>
+<tr>
+<td>4</td>
+<td><b>Narrative</b><br/>叙事</td>
+<td>Project phase milestones: Goal → What was hard → How solved → Synthesis (1-sentence reusable lesson).</td>
+<td>项目阶段里程碑：目标 → 难点 → 怎么解决的 → 提炼（一句话可复用的经验）。</td>
+<td><code>palace/pipeline/</code></td>
+</tr>
+<tr>
+<td>5</td>
+<td><b>Correction</b><br/>纠正</td>
+<td>Behavioral calibration: rules the agent must follow, with precision KPIs tracking effectiveness.</td>
+<td>行为校准：agent 必须遵守的规则，配合 precision KPI 追踪有效性。</td>
+<td><code>corrections/</code></td>
+</tr>
+<tr>
+<td>+</td>
+<td><b>Awareness</b><br/>感知</td>
+<td>Cross-project insights promoted from N-confirmed corrections. The compounding layer.</td>
+<td>跨项目的 insight，由确认 N 次以上的纠正晋升而来。复合层。</td>
+<td><code>palace/awareness</code></td>
+</tr>
+</table>
+
+All five layers share one **canonical naming grammar** (`<scope>/<type>/[<topic>/]<temporal>--<slug>.md`) so any agent — Claude, Codex, future LLM — can compose retrieval paths from intent instead of grepping five conventions. Existing files keep working via a `legacy_path` virtual-key view. No migration needed.
+
+所有五层共享一个 **规范命名语法**（`<scope>/<type>/[<topic>/]<temporal>--<slug>.md`），任何 agent —— Claude、Codex、未来的 LLM —— 都能用意图组合检索路径，不用 grep 五套命名约定。旧文件通过 `legacy_path` 虚拟键视图继续可用。无需迁移。
 
-- **Your agent learns how you think.** Humans are inconsistent — we skip from A to E, forget what we said yesterday, change priorities mid-sentence. AgentRecall captures every correction and surfaces it before the next mistake. The gap between what you mean and what your agent does shrinks with every session.
-
-- **Compounding awareness, not infinite logs.** Memory is capped at 200 lines. New insights either merge with existing ones (strengthening them) or replace the weakest. After 100 sessions, your awareness file is still 200 lines — but each line carries the weight of cross-validated, confirmed observations.
-
-- **Cross-project recall.** Lessons learned in one project apply everywhere. Built a rate limiter last month? That lesson surfaces when you're building one today — in a different repo, through a different agent.
-
-- **Near-universal compatibility.** MCP server for any MCP-compatible agent (Claude Code, Cursor, Windsurf, VS Code, Codex). SDK for any JS/TS framework (LangChain, CrewAI, Vercel AI SDK, custom agents). CLI for terminal and CI workflows. One memory system, every surface.
+---
 
-- **Zero cloud, zero telemetry, all local.** Everything is markdown on disk. Browse it in Obsidian, grep it in the terminal, version it in git. No accounts, no API keys, no lock-in.
+## The Session Loop · 会话循环
+
+<table>
+<tr>
+<th>Command</th>
+<th>When · 什么时候</th>
+<th>EN — What it does</th>
+<th>中文 — 做什么</th>
+</tr>
+<tr>
+<td>🔴 <code>/arstatus</code></td>
+<td><b>First — every session</b><br/>每个会话最先</td>
+<td>Status board across ALL projects. Pending work, blockers, relevance scores. Pick by number.</td>
+<td>所有项目的状态看板。待办、阻塞、相关性分数。按编号选。</td>
+</tr>
+<tr>
+<td><code>/arstart</code></td>
+<td>After picking a project<br/>选完项目后</td>
+<td>Load deep context: palace rooms, corrections, task-specific recall.</td>
+<td>加载深度上下文：palace 房间、纠正记录、任务相关召回。</td>
+</tr>
+<tr>
+<td>🔴 <code>/arsave</code></td>
+<td><b>Last — every session</b><br/>每个会话最后</td>
+<td>Write journal + palace consolidation + awareness compounding + semantic prefetch.</td>
+<td>写 journal + palace 合并 + awareness 复合 + 语义预取。</td>
+</tr>
+<tr>
+<td><code>/arsaveall</code></td>
+<td>End of day (multi-session)<br/>一天结束（多会话）</td>
+<td>Batch save all parallel sessions — scan, merge, deduplicate, done.</td>
+<td>批量保存所有并行会话——扫描、合并、去重、完成。</td>
+</tr>
+<tr>
+<td><code>/arbootstrap</code></td>
+<td>First install / migrating<br/>首次安装 / 迁移</td>
+<td>Scan your machine for existing projects and import them.</td>
+<td>扫描你的机器，把已有项目导入进来。</td>
+</tr>
+</table>
+
+> **Without `/arstatus`, a fresh agent has zero orientation. Without `/arsave`, nothing compounds. These two are the entire loop.**
+> 没有 `/arstatus`，新 agent 完全失去方向。没有 `/arsave`，什么都不会复合。这两个就是整个闭环。
 
 ---
 
-## Three Ways to Use It
+## Already Using Another Memory System? · 已经用过别的？
 
-**MCP** — for AI agents (Claude Code, Cursor, Windsurf, VS Code, Codex):
-```bash
-claude mcp add --scope user agent-recall -- npx -y agent-recall-mcp
-```
+**`/arbootstrap`** scans your machine and imports everything: git repos, Claude AutoMemory (`~/.claude/projects/`), CLAUDE.md files. Read-only scan, secrets never touched.
 
-**SDK** — for any JS/TS application (LangChain, CrewAI, Vercel AI SDK, custom):
-```typescript
-import { AgentRecall } from "agent-recall-sdk";
-const memory = new AgentRecall({ project: "my-app" });
-await memory.capture("What stack?", "Next.js + Postgres");
-```
+**`/arbootstrap`** 扫描你的机器并导入所有：git 仓库、Claude AutoMemory（`~/.claude/projects/`）、CLAUDE.md 文件。只读扫描，secrets 永不触碰。
 
-**CLI** — for terminal workflows and CI:
 ```bash
-npx agent-recall-cli capture "What stack?" "Next.js + Postgres"
-npx agent-recall-cli palace walk --depth active
+ar bootstrap            # scan and show what was found
+ar bootstrap --import   # import all new projects
 ```
 
 ---
 
-## What Is AgentRecall?
-
-A **learning system** that bridges the gap between how humans think and how AI agents work. Not a log. Not a database. A compounding loop where every correction, decision, and insight makes the next session better than the last.
-
-| Without AgentRecall | With AgentRecall |
-|---------------------|------------------|
-| Agent forgets yesterday's decisions | Decisions live in palace rooms, loaded on cold start |
-| Same mistake repeated across sessions | `recall_insight` surfaces past lessons before work starts |
-| 5 min context recovery on each session start | 2 second cold start from palace (~200 tokens) |
-| Flat memory files that grow forever | 200-line awareness cap forces merge-or-replace |
-| Knowledge trapped in one project | Cross-project insights match by keyword |
-| Agent misunderstands, you correct, it forgets | `alignment_check` records corrections permanently |
-
----
-
-## Quick Start
+## Quick Start · 快速开始
 
-### MCP Server (for AI agents)
+### MCP Server — for AI agents
 
 ```bash
 # Claude Code
@@ -379,14 +251,15 @@ claude mcp add --scope user agent-recall -- npx -y agent-recall-mcp
 codex mcp add agent-recall -- npx -y agent-recall-mcp
 ```
 
-**Skill (Claude Code only):**
+**Skill (Claude Code only) · 仅 Claude Code：**
+
 ```bash
 mkdir -p ~/.claude/skills/agent-recall
 curl -o ~/.claude/skills/agent-recall/SKILL.md \
   https://raw.githubusercontent.com/Goldentrii/AgentRecall/main/SKILL.md
 ```
 
-### SDK (for JS/TS applications)
+### SDK — for JS/TS applications
 
 ```bash
 npm install agent-recall-sdk
@@ -395,750 +268,300 @@ npm install agent-recall-sdk
 ```typescript
 import { AgentRecall } from "agent-recall-sdk";
 const memory = new AgentRecall({ project: "my-app" });
-await memory.coldStart();           // load context (~200 tokens)
-await memory.capture("Q", "A");     // quick capture
-await memory.palaceWrite("architecture", "Stack: Next.js + Drizzle");
+await memory.capture("What stack?", "Next.js + Postgres");
+const ctx = await memory.recall("rate limiting");
 ```
 
-### CLI (for terminal and CI)
+### CLI — for terminal & CI
 
 ```bash
-npm install -g agent-recall-cli
-ar capture "What ORM?" "Drizzle" --project my-app
-ar palace walk --depth active
-ar search "rate limiting" --include-palace
+npx agent-recall-cli capture "What stack?" "Next.js + Postgres"
+npx agent-recall-cli recall "rate limiting"
+npx agent-recall-cli palace walk --depth active
 ```
 
 ---
 
-## Semantic Recall — pgvector Backend (v3.4.0)
-
-> [!NOTE]
-> **New in v3.4.0.** Default keyword recall works without any configuration. Upgrade to Supabase + pgvector when keyword search hits its ceiling: synonyms, paraphrased queries, multi-language recall.
-
-Keyword search matches tokens. Semantic search matches **meaning**. After upgrading:
-- `recall("session expiry")` also surfaces entries about "token refresh" and "auth timeout"
-- No hand-crafted synonyms needed — embeddings handle the gap
-- Local files remain the source of truth — Supabase is a derived read index
-
-### Setup (3 steps)
-
-```bash
-# Step 1 — interactive setup wizard
-ar setup supabase
-
-# Step 2 — apply pgvector migration to your Supabase project
-ar setup supabase --migrate
-
-# Step 3 — done. Run /arstart — backfill happens automatically.
-```
-
-The wizard prompts for your Supabase project URL and service role key → writes to `~/.agent-recall/config.json`. Never committed to git.
-
-### How it works
-
-```
-remember() / session_end()
-  → writes to local ~/.agent-recall/ as always   ← source of truth, unchanged
-  → async: syncs to Supabase memories table
-      → OpenAI text-embedding-3-small (1536 dims)
-        or Voyage voyage-3-lite (512 dims, zero-padded to 1536)
-      → pgvector stores the embedding
-
-recall(query)
-  → Supabase configured?
-      YES → cosine similarity search via pgvector, reranked with local RRF
-      NO  → local keyword search (existing behavior, unchanged)
-```
-
-### Graceful degradation
-
-If Supabase is unreachable (network error, quota exceeded, not configured), `recall()` falls back to local keyword search silently. Zero behavior change if the feature is never configured.
-
-**Required:** `SUPABASE_URL` + `SUPABASE_SERVICE_ROLE_KEY` + either `OPENAI_API_KEY` or `VOYAGE_API_KEY`. All optional — AgentRecall works fully without them.
-
-**Rebuild index:** `ar setup supabase --backfill` — re-embeds all local memories into Supabase.
+## 18 MCP Tools · 18 个 MCP 工具
+
+<table>
+<tr>
+<th>Category · 类别</th>
+<th>Tool</th>
+<th>EN — What it does</th>
+<th>中文 — 做什么</th>
+</tr>
+<tr><td rowspan="6"><b>Core session</b><br/>核心会话</td>
+    <td><code>session_start</code></td><td>Load context at session start (full or <code>mode:"lite"</code> ≤500 tokens).</td><td>会话开始时加载上下文（完整或 <code>mode:"lite"</code> ≤500 tokens）。</td></tr>
+<tr><td><code>session_end</code></td><td>Save journal + insights; optionally close/open a pipeline phase in same call.</td><td>保存 journal + insights；可在同一次调用中关闭/开启 pipeline 阶段。</td></tr>
+<tr><td><code>session_end_reflect</code></td><td>Park-2023 reflection bundle — distills last N journals into reusable insights.</td><td>Park-2023 反思包——把最近 N 篇 journal 蒸馏成可复用的 insight。</td></tr>
+<tr><td><code>remember</code></td><td>Write a memory, auto-routes to the right palace room.</td><td>写入一条记忆，自动路由到合适的 palace 房间。</td></tr>
+<tr><td><code>recall</code></td><td>Search all memory (BM25 + vector with RRF fusion + Hopfield rerank).</td><td>搜索所有记忆（BM25 + 向量 + RRF 融合 + Hopfield 重排）。</td></tr>
+<tr><td><code>memory_query</code></td><td>Pull-on-demand recall mid-task. Supports file-scoped queries.</td><td>任务中按需召回。支持按文件范围查询。</td></tr>
+<tr><td rowspan="2"><b>Calibration</b><br/>校准</td>
+    <td><code>check</code></td><td>Record agent understanding; system returns predictive warnings from past corrections.</td><td>记录 agent 的理解；系统返回从过去纠正得出的预测性警告。</td></tr>
+<tr><td><code>dashboard_export</code></td><td>Generate agent-readable <code>dashboard.json</code> with all-project memory snapshot + naming index.</td><td>生成 agent 可读的 <code>dashboard.json</code>，包含所有项目记忆快照 + 命名索引。</td></tr>
+<tr><td rowspan="5"><b>Pipeline</b><br/>叙事</td>
+    <td><code>pipeline_open</code></td><td>Open a new project phase (Goal/Hard/Solved/Synthesis).</td><td>开启新的项目阶段（目标/难点/解决/提炼）。</td></tr>
+<tr><td><code>pipeline_close</code></td><td>Close active phase with reflection fields. Status: closed / abandoned / pivoted.</td><td>关闭当前阶段并填反思字段。状态：closed / abandoned / pivoted。</td></tr>
+<tr><td><code>pipeline_list</code></td><td>List all phases as JSON summaries.</td><td>列出所有阶段（JSON 摘要）。</td></tr>
+<tr><td><code>pipeline_current</code></td><td>Return full content of the currently active phase.</td><td>返回当前 active 阶段的完整内容。</td></tr>
+<tr><td><code>pipeline_show</code></td><td>Render a project's narrative spine — human-readable view of all phases.</td><td>渲染项目的叙事主干——所有阶段的人类可读视图。</td></tr>
+<tr><td rowspan="3"><b>Skills</b><br/>程序记忆</td>
+    <td><code>skill_write</code></td><td>Save an IF-THEN production rule (trigger / preconditions / steps / postconditions / pitfalls).</td><td>保存一条 IF-THEN 产生式规则（触发条件/前提/步骤/后置条件/陷阱）。</td></tr>
+<tr><td><code>skill_recall</code></td><td>Find skills matching an intent (deterministic trigger-keyword ranking).</td><td>按意图找到匹配的 skill（基于触发关键词的确定性排序）。</td></tr>
+<tr><td><code>skill_list</code></td><td>Browse all skills in a project.</td><td>浏览项目中所有 skill。</td></tr>
+<tr><td><b>Setup</b><br/>初始化</td>
+    <td><code>bootstrap_scan</code> + <code>bootstrap_import</code></td><td>Discover existing projects on this machine and import in bulk.</td><td>发现本机已有项目并批量导入。</td></tr>
+</table>
 
 ---
 
-## How an Agent Uses AgentRecall
-
-### Automatic (Zero Discipline — Hooks)
-
-Wire once in `~/.claude/settings.json`. Every session is captured automatically, even without `/arsave`:
-
-```json
-{
-  "hooks": {
-    "SessionStart": [{
-      "command": "node ~/.local/share/npm/lib/node_modules/agent-recall-cli/dist/index.js hook-start 2>/dev/null || true"
-    }],
-    "UserPromptSubmit": [{
-      "command": "node ~/.local/share/npm/lib/node_modules/agent-recall-cli/dist/index.js hook-correction 2>/dev/null || true"
-    }],
-    "Stop": [{
-      "command": "node ~/.local/share/npm/lib/node_modules/agent-recall-cli/dist/index.js hook-end 2>/dev/null || true"
-    }]
-  }
-}
-```
-
-- **hook-start** — on every session open: prints identity + top insights + watch_for warnings
-- **hook-correction** — on every prompt: detects corrections (regex) and captures them silently
-- **hook-end** — on every session close: appends a lightweight end-of-session log entry
-
-### Session Start (`/arstart`)
-```
-session_start()  → identity, insights, active rooms, cross-project matches,
-                   recent journal briefs, watch_for warnings — all in one call
-recall(query)    → surface task-specific past knowledge from all stores
-```
-
-### During Work
-```
-remember("We decided to use GraphQL instead of REST")  → auto-routes to the right store
-recall("authentication design")                          → searches all stores, ranked results
-check(goal="build auth", confidence="medium")            → verify understanding, get warnings
-```
-
-### Session End (`/arsave`)
-```
-session_end(summary="...", insights=[...], trajectory="...")  → journal + awareness + consolidation
-```
+## How Memory Compounds · 记忆如何复合
+
+<table>
+<tr>
+<th>Mechanism · 机制</th>
+<th>EN</th>
+<th>中文</th>
+</tr>
+<tr>
+<td><b>Auto-naming</b></td>
+<td>Files name themselves from content via canonical grammar — agents compose paths from intent, no guessing.</td>
+<td>文件根据内容用规范语法自命名——agent 按意图组合路径，不用猜。</td>
+</tr>
+<tr>
+<td><b>FSRS-lite decay</b></td>
+<td><code>R = exp(-days_since_lastConfirmed / S)</code>. Each recall hit reinforces stability. Cold facts get tagged <code>archive_candidate</code> instead of silently growing forever.</td>
+<td><code>R = exp(-距上次确认天数 / S)</code>。每次召回命中会强化稳定性。冷的事实会被标 <code>archive_candidate</code>，而不是静默无限增长。</td>
+</tr>
+<tr>
+<td><b>RRF + Hopfield retrieval</b></td>
+<td>BM25 + vector merged via RRF (Cormack 2009), then optionally re-ranked by Modern Hopfield (Ramsauer 2020) for associative blend.</td>
+<td>BM25 + 向量通过 RRF 融合（Cormack 2009），再可选地用 Modern Hopfield 重排（Ramsauer 2020）做关联融合。</td>
+</tr>
+<tr>
+<td><b>Correction precision KPI</b></td>
+<td>Every correction tracks <code>precision = heeded / retrieved</code>. <0.3 → archive candidate (noise). ≥0.8 → promote faster.</td>
+<td>每条纠正跟踪 <code>precision = 被遵守 / 被召回</code>。<0.3 → archive 候选（噪声）。≥0.8 → 加速晋升。</td>
+</tr>
+<tr>
+<td><b>Cross-project insights</b></td>
+<td>Lessons learned in one project surface when you're working on a similar problem in another. Match by keyword + topic.</td>
+<td>一个项目学到的经验，在另一个相似问题上会自动浮现。按关键词 + 主题匹配。</td>
+</tr>
+<tr>
+<td><b>Awareness cap</b></td>
+<td>Capped at 200 lines. New insights merge with existing (strengthening) or replace the weakest. After 100 sessions: still 200 lines, but cross-validated.</td>
+<td>上限 200 行。新 insight 与已有合并（加强）或替换最弱的。100 次会话之后：仍然 200 行，但都是经过交叉验证的。</td>
+</tr>
+</table>
 
 ---
 
-## 10 MCP Tools
-
-AgentRecall exposes 10 tools to agents. Each tool composes multiple subsystems internally — the agent doesn't need to know about the plumbing.
-
-| Tool | What it does |
-|------|-------------|
-| `session_start` | Load project context for a new session. Returns identity, top insights, active rooms, cross-project matches, recent activity, and predictive `watch_for` warnings from past corrections. One call, ~400 tokens. |
-| `remember` | Save a memory. Auto-classifies content (bug fix, architecture decision, insight, session note) and routes to the right store (journal, palace, knowledge, or awareness). Auto-generates semantic names for future retrieval. |
-| `recall` | Search all memory stores at once using **Reciprocal Rank Fusion (RRF)** — each source ranks internally, then positions are merged so no source dominates by default. Returns ranked results with stable IDs. Accepts `feedback` to rate previous results: positive boosts future ranking, negative penalizes. Query-aware — feedback from one search doesn't bleed into unrelated queries. |
-| `session_end` | Save everything in one call. Writes journal, updates awareness with new insights, consolidates to palace rooms, archives demoted insights (not deleted — preserved with resurrection support). |
-| `check` | Record what you think the human wants. Returns `watch_for` patterns from past correction history ("You've been corrected on X 3 times — ask about it"). Accepts `human_correction` and `delta` after the human responds. Auto-promotes strong patterns (3+) to awareness. |
-| `digest` | **Context cache** — store pre-computed analysis results (codebase audits, subagent explorations) and recall them instead of recomputing. Actions: `store`, `recall`, `read`, `invalidate`. Scoring uses Ebbinghaus decay with Zipf-adjusted half-life. **Benchmarked: 83% token savings on repeated analysis vs. recompute.** |
-| `project_board` | Status board across all AgentRecall projects — same data as `/arstatus`. Returns numbered project list with pending work, blockers, and last activity. Use at the start of any multi-project session. |
-| `project_status` | Deep status for a single project — next actions, blockers, recent journal summary, palace room health. Use after `project_board` to pick and focus. |
-| `bootstrap_scan` | Scan the machine for existing projects (git repos, Claude AutoMemory, CLAUDE.md files). Read-only — no writes. Returns scan results for review before import. |
-| `bootstrap_import` | Import projects discovered by `bootstrap_scan` into AgentRecall. Writes identity, architecture, memory, and trajectory to `~/.agent-recall/`. Safe: never modifies source files. |
-
-### Legacy tools
-
-The original 22 subsystem tools (palace_write, journal_capture, awareness_update, etc.) remain available via the SDK and CLI for backward compatibility and advanced use cases. They are not registered in the MCP server by default.
-
----
-
-## How Memory Compounds
-
-<p align="center">
-  <a href="#1-auto-naming"><img src="https://img.shields.io/badge/1-AUTO--NAMING-5D34F2?style=for-the-badge" alt="Auto-Naming"></a>
-  <a href="#2-indexes"><img src="https://img.shields.io/badge/2-INDEXES-0EA5E9?style=for-the-badge" alt="Indexes"></a>
-  <a href="#3-relativity"><img src="https://img.shields.io/badge/3-RELATIVITY-10B981?style=for-the-badge" alt="Relativity"></a>
-  <a href="#4-weight--decay"><img src="https://img.shields.io/badge/4-WEIGHT_%2B_DECAY-F59E0B?style=for-the-badge" alt="Weight + Decay"></a>
-  <a href="#5-feedback-loop"><img src="https://img.shields.io/badge/5-FEEDBACK_LOOP-EF4444?style=for-the-badge" alt="Feedback Loop"></a>
-</p>
-
-> Memory is not a list. It's a compounding system where 1+1+1 > 3. Each subsystem feeds the next — naming enables retrieval, retrieval enables feedback, feedback enables ranking, ranking surfaces the right memory at the right time.
-
-### 1. Auto-Naming
-
-The agent knows content best at the moment of saving. AgentRecall captures that understanding in a semantic slug — not `"mcp-verified"` but `"verified-agentrecall-mcp-22tools-functional"`. Good naming IS the first layer of retrieval. A well-named memory is 80% findable without any search algorithm.
-
-**File naming:** `{date}--{saveType}--{lines}L--{slug}.md` — parseable by agents (`split("--")` → `[date, type, size, topic]`), readable by humans. Line count tells the agent the token cost before opening the file.
-
-### 2. Indexes
-
-| Index | What it tracks | Token cost |
-|-------|---------------|------------|
-| **Palace index** | Room catalog + salience scores | ~50 tokens to scan |
-| **Insights index** | Cross-project lessons + keyword matching | ~30 tokens to query |
-| **Awareness** | 200-line compounding document (forced merge) | ~200 tokens, each line cross-validated |
-
-### 3. Relativity
-
-Memories that relate to each other are connected automatically — no wikilinks needed. When you `recall("session security")`, the system surfaces keyword-matched memories across connected rooms. Edges are stored in `graph.json` — relativity turns isolated memories into a knowledge graph.
-
-### 4. Weight + Decay
-
-Not all memories are equal. Salience scoring: `recency(0.30) + access(0.25) + connections(0.20) + urgency(0.15) + importance(0.10)`
-
-`recall` applies the **Ebbinghaus forgetting curve** `R(t) = e^(−t/S)` with memory-type-specific strength values:
-
-| Memory type | S (days) | 1-day retention | 1-week retention |
-|-------------|----------|-----------------|------------------|
-| Journal (episodic) | 2 | 60% | ~7% |
-| Knowledge / bug fix (procedural) | 180 | 99% | 96% |
-| Palace / decisions (semantic) | 9999 | ≈100% | ≈100% |
-
-Old journal noise fades in days. Architecture decisions persist indefinitely. **Hot-window boost:** Items from the last 6 hours get a 3× score multiplier, last 24 hours get 2×, last 72 hours get 1.3×.
-
-### 5. Feedback Loop
-
-The system uses a **Bayesian Beta distribution** — the mathematically optimal estimate of true usefulness from binary observations (`E[Beta(α,β)] = (pos+1)/(pos+neg+2)`). Rating a result "useless" for one query doesn't penalize it for unrelated queries. Feedback is query-aware, not global.
-
-> **Feedback is now automatic.** The ambient recall hook tracks which memories were surfaced. Human's next message is a correction → negative feedback. Not a correction → positive feedback. No agent action required.
-
-### The Compounding Effect
-
-```
-Session 1:   Save 3 memories (auto-named, indexed, edges created)
-Session 5:   Recall surfaces memories from sessions 1-4, feedback refines ranking
-Session 10:  watch_for warns agent about past mistakes before they repeat
-Session 20:  Awareness contains 10 cross-validated insights (merged from 40+ raw observations)
-Session 50:  The agent knows your priorities, blind spots, and communication style
-             — not because it was told, but because every correction compounded
-```
-
-**Stemming + synonyms:** "deploying" matches "deployment," "ship," and "release." A 19-rule suffix stemmer + 100-pair synonym table — no vector DB needed (keyword mode), zero external dependencies.
+## What's New in Phase 6 · Phase 6 新增
+
+Phase 6 closes 11 structural gaps the field's research literature flagged. Three improvement loops in one pass — 10-vantage research review → implementation → independent code review → fix-up.
+
+Phase 6 修复了研究文献指出的 11 个结构性缺口。一次完成三个改进循环——10 视角研究审查 → 实现 → 独立代码审查 → 修复。
+
+<table>
+<tr>
+<th>Change · 改动</th>
+<th>Research grounding · 研究依据</th>
+</tr>
+<tr>
+<td><b>Pipeline layer</b> — project narrative spine with 5 MCP tools<br/><b>叙事层</b> — 项目叙事主干 + 5 个 MCP 工具</td>
+<td>Park et al. 2023 (Generative Agents) reflection pattern</td>
+</tr>
+<tr>
+<td><b>Canonical naming system</b> — virtual key + <code>legacy_path</code>, no migration needed<br/><b>规范命名系统</b> — 虚拟键 + <code>legacy_path</code>，无需迁移</td>
+<td>Squire 2004 taxonomy + CoALA architecture</td>
+</tr>
+<tr>
+<td><b>Procedural memory (5th layer)</b> — <code>palace/skills/</code> + 3 MCP tools<br/><b>程序记忆（第 5 层）</b> — <code>palace/skills/</code> + 3 个 MCP 工具</td>
+<td>Squire 2004 declarative/non-declarative split, ACT-R production rules</td>
+</tr>
+<tr>
+<td><b>Correction outcome KPIs</b> — precision / heeded / recurrence tracking<br/><b>纠正结果 KPI</b> — precision / heeded / recurrence 追踪</td>
+<td>Reflexion (Shinn 2023), RLAIF — making the learning loop measurable</td>
+</tr>
+<tr>
+<td><b>FSRS-lite decay scorer</b> — reinforce on recall, decay on staleness<br/><b>FSRS-lite 衰减打分</b> — 召回时强化，过期时衰减</td>
+<td>Ebbinghaus 1885 → SuperMemo → FSRS-6 (Anki ≥23.10)</td>
+</tr>
+<tr>
+<td><b>Modern Hopfield re-ranker</b> — <code>ξ_new = X·softmax(β·X^⊤·ξ)</code><br/><b>Modern Hopfield 重排</b> — <code>ξ_new = X·softmax(β·X^⊤·ξ)</code></td>
+<td>Ramsauer et al. 2020, exp(d/2) capacity vs classical 0.14·d</td>
+</tr>
+<tr>
+<td><b>session_start lite mode</b> — ≤500 tokens, pull-on-demand<br/><b>session_start lite 模式</b> — ≤500 tokens，按需召回</td>
+<td>Anthropic 2026 context engineering — "smallest high-signal set"</td>
+</tr>
+<tr>
+<td><b>Agent-readable dashboard.json</b> — schema_version=1, one-call self-inspection<br/><b>Agent 可读的 dashboard.json</b> — schema_version=1，一次调用自查</td>
+<td>Agent-first principle — humans aren't the only readers</td>
+</tr>
+<tr>
+<td><b>Reflection bundle</b> — Park-style aggregation prompt (LLM call happens in the agent's turn, not core)<br/><b>反思包</b> — Park 风格的聚合 prompt（LLM 调用在 agent 自己的 turn 里，不在 core）</td>
+<td>Park 2023 §4.3</td>
+</tr>
+<tr>
+<td><b>Security hardening</b> — path traversal blocked, frontmatter YAML escaped, atomic writes, line-walk section parser<br/><b>安全加固</b> — 路径穿越封堵、frontmatter YAML 转义、原子写入、按行解析章节</td>
+<td>8-agent red-team P0 findings (2026-05-30)</td>
+</tr>
+</table>
+
+Full details: see [`UPDATE-LOG.md`](./UPDATE-LOG.md) Phase 6 section. Visual report: [`REPORT-2026-05-30.html`](./REPORT-2026-05-30.html).
+
+完整细节见 [`UPDATE-LOG.md`](./UPDATE-LOG.md) Phase 6 章节。可视化报告：[`REPORT-2026-05-30.html`](./REPORT-2026-05-30.html)。
 
 ---
 
 ## SDK API
 
-The `agent-recall-sdk` package exposes the `AgentRecall` class — a programmatic interface to the full memory system. Use it to add persistent, compounding memory to any JS/TS agent framework.
-
 ```typescript
 import { AgentRecall } from "agent-recall-sdk";
-const ar = new AgentRecall({ project: "my-project" });
-```
-
-### Core Methods
-
-| Method | Returns | Description |
-|--------|---------|-------------|
-| `capture(question, answer, opts?)` | `JournalCaptureResult` | Quick Q&A capture (L1 memory) |
-| `journalWrite(content, opts?)` | `JournalWriteResult` | Write daily journal entry |
-| `journalRead(opts?)` | `JournalReadResult` | Read journal by date or "latest" |
-| `journalSearch(query, opts?)` | `JournalSearchResult` | Full-text search across journals |
-| `coldStart()` | `JournalColdStartResult` | Palace-first context loading (~200 tokens) |
-
-### Palace Methods
-
-| Method | Returns | Description |
-|--------|---------|-------------|
-| `palaceWrite(room, content, opts?)` | `PalaceWriteResult` | Write to a room with fan-out cross-refs |
-| `palaceRead(room?, topic?)` | `PalaceReadResult` | Read room content or list all rooms |
-| `walk(depth?, focus?)` | `PalaceWalkResult` | Progressive walk: identity → active → relevant → full |
-| `palaceSearch(query, room?)` | `PalaceSearchResult` | Search rooms by content |
-| `lint(fix?)` | `PalaceLintResult` | Health check and auto-archive |
-
-### Awareness & Insight Methods
-
-| Method | Returns | Description |
-|--------|---------|-------------|
-| `awarenessUpdate(insights, opts?)` | `AwarenessUpdateResult` | Compound new insights into awareness |
-| `readAwareness()` | `string` | Read the 200-line awareness document |
-| `recallInsight(context, opts?)` | `RecallInsightResult` | Cross-project insight recall |
-
-### Alignment Methods
-
-| Method | Returns | Description |
-|--------|---------|-------------|
-| `alignmentCheck(input)` | `AlignmentCheckResult` | Record confidence + assumptions |
-| `nudge(input)` | `NudgeResult` | Detect contradictions with past decisions |
-| `synthesize(opts?)` | `ContextSynthesizeResult` | L3 synthesis, optional palace consolidation |
-
----
-
-## CLI Commands
-
-The `agent-recall-cli` package provides the `ar` command for terminal workflows and CI pipelines.
-
-```
-ar v3.4.0 — AgentRecall CLI
-
-JOURNAL:
-  ar read [--date YYYY-MM-DD] [--section <name>]
-  ar write <content> [--section <name>]
-  ar capture <question> <answer> [--tags tag1,tag2]
-  ar list [--limit N]
-  ar search <query> [--include-palace]
-  ar state read|write [data]
-  ar cold-start
-  ar archive [--older-than-days N]
-  ar rollup [--min-age-days N] [--dry-run]
-
-PALACE:
-  ar palace read [<room>] [--topic <name>]
-  ar palace write <room> <content> [--importance high|medium|low]
-  ar palace walk [--depth identity|active|relevant|full]
-  ar palace search <query>
-  ar palace lint [--fix]
-
-AWARENESS:
-  ar awareness read
-  ar awareness update --insight "title" --evidence "ev" --applies-when kw1,kw2
-
-INSIGHT:
-  ar insight <context> [--limit N]
-
-SETUP:
-  ar setup supabase                 # interactive Supabase setup wizard
-  ar setup supabase --migrate       # apply pgvector migration
-  ar setup supabase --backfill      # re-embed all local memories
-
-META:
-  ar projects
-  ar synthesize [--entries N]
-  ar knowledge write --category <cat> --title "t" --what "w" --cause "c" --fix "f"
-  ar knowledge read [--category <cat>]
-  ar bootstrap [--dry-run] [--import] [--project X]
-
-HOOKS (auto-wired via settings.json — zero discipline required):
-  ar hook-start      # SessionStart: prints identity + insights + watch_for
-  ar hook-correction # UserPromptSubmit: silently captures corrections from prompt
-  ar hook-end        # Stop: appends end-of-session log entry
-
-GLOBAL FLAGS:
-  --root <path>     Storage root (default: ~/.agent-recall)
-  --project <slug>  Project override
-```
-
----
-
-## Architecture
-
-### Five-Layer Memory Pyramid
-
-```
-L1: Working Memory     journal_capture           "what happened"
-L2: Episodic Memory    journal_write             "what it means"
-L3: Memory Palace      palace_write / walk       "knowledge across sessions"
-L4: Awareness          awareness_update          "compounding insights"
-L5: Insight Index      recall_insight            "cross-project experience"
-```
-
-### Key Mechanisms
-
-**Fan-out writes** — Write to one room, cross-references auto-update in related rooms via `[[wikilinks]]`. Mechanical, zero LLM cost.
-
-**Salience scoring** — Every room has a salience score: `recency(0.30) + access(0.25) + connections(0.20) + urgency(0.15) + importance(0.10)`. High-salience rooms surface first. Below threshold → auto-archive.
-
-**Compounding awareness** — `awareness.md` is capped at 200 lines. When new insights are added, similar existing ones merge (strengthen), dissimilar ones compete (lowest-confirmation gets replaced). The constraint creates compression. Compression creates compounding.
-
-**Cross-project insight recall** — `insights-index.json` maps insights to situations via keywords. `recall_insight("building quality gates")` returns relevant lessons from any project, ranked by severity x confirmation count.
 
-**Obsidian-compatible** — Every palace file has YAML frontmatter + `[[wikilinks]]`. Open `palace/` as an Obsidian vault → graph view shows room connections. Zero Obsidian dependency.
-
-### Storage Layout
-
-```
-~/.agent-recall/
-  awareness.md                    # 200-line compounding document (global)
-  awareness-state.json            # Structured awareness data
-  awareness-archive.json          # Demoted insights (preserved, not deleted)
-  insights-index.json             # Cross-project insight matching
-  config.json                     # Optional: Supabase URL + keys (never git-committed)
-  projects/
-    <project>/
-      journal/
-        YYYY-MM-DD.md             # Daily journal
-        YYYY-MM-DD-log.md         # L1 captures (hook-start/hook-end entries)
-        YYYY-MM-DD.state.json     # JSON state
-        index.jsonl               # Fast machine-scannable index of all entries
-      palace/
-        identity.md               # ~50 token project identity card
-        palace-index.json          # Room catalog + salience scores
-        graph.json                 # Cross-reference edges (relativity)
-        feedback-log.json          # Per-query feedback scores (recall learning)
-        alignment-log.json         # Past corrections for watch_for patterns
-        rooms/
-          goals/                   # Active goals, evolution
-          architecture/            # Technical decisions, patterns
-          decisions/               # Decision trails with prior/posterior tracking
-          blockers/                # Current and resolved
-          alignment/               # Human corrections
-          knowledge/               # Learned lessons by category
-          <custom>/                # Agents create rooms on demand
-```
-
----
-
-## Platform Compatibility
-
-| Platform | MCP | SDK | CLI | Notes |
-|----------|:---:|:---:|:---:|-------|
-| Claude Code | ✅ | ✅ | ✅ | Full support — MCP + SKILL.md + commands |
-| Cursor | ✅ | ✅ | ✅ | MCP via .cursor/mcp.json |
-| VS Code (Copilot) | ✅ | ✅ | ✅ | MCP via .vscode/mcp.json |
-| Windsurf | ✅ | ✅ | ✅ | MCP via mcp_config.json |
-| OpenAI Codex | ✅ | ✅ | ✅ | `codex mcp add` — config.toml |
-| Claude Desktop | ✅ | — | — | MCP server |
-| LangChain / LangGraph | — | ✅ | — | `new AgentRecall()` in your chain |
-| CrewAI | — | ✅ | — | SDK in tool definitions |
-| Vercel AI SDK | — | ✅ | — | SDK in server actions |
-| Custom JS/TS agents | — | ✅ | ✅ | SDK + CLI for any agent framework |
-| CI / GitHub Actions | — | — | ✅ | `npx agent-recall-cli` in workflows |
-| Any MCP agent | ✅ | — | — | Standard MCP protocol |
-
----
-
-## Benchmarked Token Savings
-
-We ran two controlled benchmarks: a 5-round A/B test (Next.js + Drizzle + Stripe project) and a 10-round v3.3.16 benchmark validating `digest` cache, `arsaveall`, and cross-project recall. **Read this table honestly:** for simple throwaway tasks, AR is pure overhead. For anything with 3+ sessions, corrections, or multiple agents, it pays for itself — and the savings compound.
-
-| Scenario | Without AR | With AR | **Saved** |
-|----------|:---------:|:------:|:--------:|
-| **A: Simple** (2 sessions, 0 corrections) | 567 | 1,131 | **+99% overhead** |
-| **B: Medium** (5 sessions, 1 correction) | 6,220 | 4,382 | **-30%** |
-| **C: Complex** (20 sessions, 5 corrections) | 40,910 | 17,520 | **-57%** |
-| **D: Multi-agent** (3 agents × 5 sessions) | 20,781 | 13,140 | **-37%** |
-| **E: Digest cache** (repeated analysis, 1 recall hit) | ~2,400 | ~400 | **-83%** |
-
-**Break-even: ~3-4 sessions.** After that, every session with AR is cheaper than without.
-
-### Where the Savings Come From
-
-| Source | Without AR cost | With AR cost | Why |
-|--------|:-:|:-:|-----|
-| **Context rebuild** | Up to ~1,100+ tokens/session | Fixed ~385 tokens (cold start) | AR loads palace context in one call |
-| **Correction retention** | ~800 tokens per repeat | 0 (stored once, never repeated) | Biggest single savings driver in long projects |
-| **Clarification avoidance** | ~400 tokens/session | 0 (already loaded) | Steady per-session savings |
-| **Cross-project recall** | ~500 tokens per insight | ~350 tokens (automatic recall) | Compounds across projects |
-| **Digest cache** | ~2,400 tokens (full re-analysis) | ~400 tokens (recall stored digest) | 83% savings on repeated heavy analysis |
-
-All benchmark code: [`benchmark/run.mjs`](benchmark/run.mjs), [`benchmark/ab-comparison.mjs`](benchmark/ab-comparison.mjs), and [`benchmark/v3316-benchmark.mjs`](benchmark/v3316-benchmark.mjs). Run them yourself: `node benchmark/run.mjs && node benchmark/ab-comparison.mjs`.
-
----
-
-## Docs
-
-| Document | Description |
-|----------|-------------|
-| **[→ Command Reference](docs/commands.md)** | **Full guide to `/arstatus`, `/arstart`, `/arsave`, `/arsaveall` — example outputs, modes, palace rules, troubleshooting** |
-| [Intelligent Distance Protocol](docs/intelligent-distance-protocol.md) | The foundational theory — why the gap between human and AI is structural, and how to navigate it |
-| [Scoring Design Rationale](docs/SCORING.md) | Why the scoring system works this way — RRF, Ebbinghaus, Beta distribution, and the bugs they fix |
-| [MCP Adapter Spec](docs/mcp-adapter-spec.md) | Technical spec for building adapters on top of AgentRecall |
-| [SDK Design](docs/sdk-design.md) | Design doc for the SDK architecture |
-| [Upgrade v3.4](UPGRADE-v3.4.md) | Changelog: semantic recall, pgvector backend, 10 MCP tools, bootstrap, palace decisions room |
-| [MCP Server README](packages/mcp-server/README.md) | Focused guide for Claude Code / Cursor / Windsurf users |
-| [Core SDK README](packages/core/README.md) | SDK API reference for building with AgentRecall programmatically |
-
----
-
-## Contributing
-
-Built by [tongwu](https://github.com/Goldentrii) at [Novada](https://www.novada.com).
-
-- Issues & feedback: [GitHub Issues](https://github.com/Goldentrii/AgentRecall/issues)
-- Email: [tong.wu@novada.com](mailto:tong.wu@novada.com)
-- Website: [novada.com](https://www.novada.com)
-
-MIT License.
-
----
-
----
-
-# AgentRecall（中文文档）
-
-> **你的智能体记不清楚？听不懂你说话？每次项目都做得非常乱？**
->
-> **AgentRecall 让它学会理解你的思维方式。**
->
-> 赋能agent长期记忆，并从错误中学习和纠正，随时间和项目难度进化，越来越擅长和了解用户和agent的思维。
->
-> 持久复合记忆 + 智能距离协议。MCP 服务器 + SDK + CLI。
-
----
-
-<p align="center">
-  <a href="#arstatus-arsave-arstart-和-arsaveall"><img src="https://img.shields.io/badge/%2Farstatus-从这里开始-22C55E?style=for-the-badge" alt="/arstatus"></a>
-  <a href="#arstatus-arsave-arstart-和-arsaveall"><img src="https://img.shields.io/badge/%2Farstart-加载上下文-4ECDC4?style=for-the-badge" alt="/arstart"></a>
-  <a href="#arstatus-arsave-arstart-和-arsaveall"><img src="https://img.shields.io/badge/%2Farsave-保存会话-FF6B6B?style=for-the-badge" alt="/arsave"></a>
-  <a href="#arstatus-arsave-arstart-和-arsaveall"><img src="https://img.shields.io/badge/%2Farsaveall-批量保存-FFD93D?style=for-the-badge" alt="/arsaveall"></a>
-</p>
-<p align="center">
-  <img src="https://img.shields.io/badge/自动-hook--start-8B5CF6?style=for-the-badge" alt="hook-start">
-  <img src="https://img.shields.io/badge/自动-hook--correction-F97316?style=for-the-badge" alt="hook-correction">
-  <img src="https://img.shields.io/badge/自动-hook--end-06B6D4?style=for-the-badge" alt="hook-end">
-</p>
-
-## `/arstatus`、`/arsave`、`/arstart` 和 `/arsaveall`
-
-> [!IMPORTANT]
-> **每次新会话都先运行 `/arstatus`。** 它会显示你所有项目的状态、待完成的工作、阻塞项，让你用数字选择下一步——无需记住项目名称。没有它，全新的 agent 根本不知道从哪里开始。
-
-| 命令 | 时机 | 功能 |
-|------|------|------|
-| ⭐ **`/arstatus`** | **每次会话——先运行这个** | **跨所有项目的状态看板：待办事项、阻塞项、编号选择列表。真正的冷启动。** |
-| **`/arstart`** | 选好项目后 | 加载单个项目的深度上下文：宫殿房间、纠正记录、任务相关召回 |
-| **`/arsave`** | 会话结束时 | 写入日志 + 整合到记忆宫殿 + 更新感知 |
-| **`/arsaveall`** | 一天结束时（多会话） | **一次性批量保存所有并行会话** — 扫描、合并、去重、完成 |
-
-**会话流程：** `/arstatus` → 输入编号 → `/arstart <项目>` → 工作 → `/arsave`。
-
-### 你会看到什么
-
-输入 `/arstatus` → 一眼看清所有项目进展：
-
-```
-──────────────────────────────────────────────────────────────
-  AgentRecall  状态看板        2026-04-21    5 个项目
-──────────────────────────────────────────────────────────────
+const memory = new AgentRecall({ project: "my-app" });
 
-  1  ⚠ novada-site       2026-04-21   阻塞
-       阻塞：缺少 .env.local — Phase 1 无法继续
+// Write — auto-routes to journal / palace / awareness based on content
+await memory.capture("What stack?", "Next.js + Postgres + Drizzle ORM");
+await memory.remember("Database: pgvector enabled, RRF fusion for hybrid recall");
 
-  2  ● novada-mcp        2026-04-21
-       下一步：修复 novada_search POST /request → 发布 v0.8.0
+// Read — full hybrid search
+const results = await memory.recall("rate limiting");
+const filescoped = await memory.recall("auth flow", { file_path: "src/auth.ts" });
 
-  3  ● prismma-scraper   2026-04-17
-       下一步：UI 升级 Option A — 浅色模式 + 3D 视觉
+// Reflect — bundle recent journals + corrections for LLM-side distillation
+const bundle = await memory.reflect({ lookback_days: 7 });
 
-  4  ✓ AgentRecall       2026-04-21   已完成
-       收集真实生产数据中
+// Pipeline — track project narrative
+await memory.pipelineOpen({ phase_name: "Discovery", goal: "Map user pain points" });
+await memory.pipelineClose({
+  what_was_hard: "Conflicting signals from interviews",
+  how_solved: "Triangulated against analytics data",
+  synthesis: "Behavior > stated preference when they diverge"
+});
 
-──────────────────────────────────────────────────────────────
-  输入编号，或：
-    N  新项目（带记忆——agent 了解你的完整历史）
-    X  新项目（空白状态——无历史上下文，纯客观模式）
-──────────────────────────────────────────────────────────────
-```
-
-### 效果对比
-
-| 没有 AgentRecall | 有 AgentRecall |
-|-----------------|---------------|
-| 智能体忘记昨天的决策 | 决策存在宫殿房间，冷启动时加载 |
-| 跨会话重复同样的错误 | `recall_insight` 工作前自动呈现过去教训 |
-| 每次开始需要 5 分钟恢复上下文 | 2 秒冷启动，从宫殿加载（~200 token） |
-| 平面记忆文件无限增长 | 200 行感知上限，强制合并或替换 |
-| 知识锁在单个项目 | 跨项目洞察按关键词匹配 |
-
-```bash
-# 安装命令（一次性，仅 Claude Code）
-mkdir -p ~/.claude/commands
-curl -o ~/.claude/commands/arstatus.md https://raw.githubusercontent.com/Goldentrii/AgentRecall/main/commands/arstatus.md
-curl -o ~/.claude/commands/arstart.md https://raw.githubusercontent.com/Goldentrii/AgentRecall/main/commands/arstart.md
-curl -o ~/.claude/commands/arsave.md https://raw.githubusercontent.com/Goldentrii/AgentRecall/main/commands/arsave.md
-curl -o ~/.claude/commands/arsaveall.md https://raw.githubusercontent.com/Goldentrii/AgentRecall/main/commands/arsaveall.md
+// Skills — save and recall procedural know-how
+await memory.skillWrite({
+  name: "Cloudflare 4-step routing",
+  topic: "deploy",
+  triggers: ["cloudflare", "dns", "ssl"],
+  when: "Setting up a new domain with API gateway behind Cloudflare",
+  steps: ["Add DNS record", "Enable Proxy", "Add Origin Rule", "Set SSL mode = Full"]
+});
+const hits = await memory.skillRecall({ intent: "set up cloudflare for new domain" });
 ```
 
 ---
 
-## 快速开始
+## CLI
 
 ```bash
-# Claude Code
-claude mcp add --scope user agent-recall -- npx -y agent-recall-mcp
+# Capture & recall
+ar capture "Question" "Answer"
+ar recall "topic"                # hybrid BM25 + vector + Hopfield re-rank
+ar recall "topic" --since 7d     # time-filtered
 
-# Cursor — .cursor/mcp.json
-{ "mcpServers": { "agent-recall": { "command": "npx", "args": ["-y", "agent-recall-mcp"] } } }
+# Sessions
+ar status                        # status board across all projects
+ar save                          # full session_end (journal + palace + awareness)
+ar saveall                       # batch save all parallel sessions
 
-# VS Code — .vscode/mcp.json
-{ "servers": { "agent-recall": { "command": "npx", "args": ["-y", "agent-recall-mcp"] } } }
+# Bootstrap
+ar bootstrap                     # scan and show
+ar bootstrap --import            # import all new projects
 
-# Codex
-codex mcp add agent-recall -- npx -y agent-recall-mcp
-```
+# Palace navigation
+ar palace walk --depth active    # browse active rooms
+ar palace read goals             # read a room
 
-**Claude Code 技能安装：**
-```bash
-mkdir -p ~/.claude/skills/agent-recall
-curl -o ~/.claude/skills/agent-recall/SKILL.md \
-  https://raw.githubusercontent.com/Goldentrii/AgentRecall/main/SKILL.md
+# Pipeline
+ar pipeline show <project>       # narrative spine
+ar pipeline list <project>       # JSON summaries
 ```
 
----
-
-## 语义召回 — pgvector (v3.4.0)
-
-> [!NOTE]
-> **v3.4.0 新功能。** 默认关键词召回无需任何配置。当关键词搜索遇到天花板时——同义词、改写查询、多语言——升级到 Supabase pgvector 后端。
-
-关键词搜索匹配词汇，语义搜索匹配**含义**。升级后：`recall("会话过期")` 也能找到"token 刷新"和"认证超时"相关的条目，无需手动添加同义词。
-
-```bash
-# 第 1 步 — 交互式配置向导
-ar setup supabase
-
-# 第 2 步 — 将 pgvector 迁移应用到你的 Supabase 项目
-ar setup supabase --migrate
-
-# 第 3 步 — 完成。运行 /arstart — 下次会话自动回填。
-```
-
-本地文件仍为数据源。Supabase 是派生的读取索引 — 随时可删除并用 `ar setup supabase --backfill` 重建。
-
-**所需环境变量：** `SUPABASE_URL` + `SUPABASE_SERVICE_ROLE_KEY` + `OPENAI_API_KEY`（或 `VOYAGE_API_KEY`）。全部可选 — 不配置时 AgentRecall 完全正常运行。
-
-**优雅降级：** Supabase 不可达时，`recall()` 静默回退到本地关键词搜索，零行为变化。
-
----
-
-## 10 个 MCP 工具
-
-AgentRecall 目前向 agent 提供 10 个工具。每个工具内部组合多个子系统——agent 不需要了解内部管道。
-
-| 工具 | 功能 |
-|------|------|
-| `session_start` | 加载项目上下文。返回身份、洞察、活跃房间、跨项目匹配、watch_for 预警。约 400 token。 |
-| `remember` | 保存记忆。自动分类并路由到正确的存储（日志、宫殿、知识库或感知系统）。 |
-| `recall` | 通过 **RRF** 一次搜索所有记忆。支持 `feedback` 评价：正面提升排名，负面降低。查询感知。 |
-| `session_end` | 一次调用保存全部：写日志、更新感知、整合宫殿、归档被替换洞察。 |
-| `check` | 记录对人类意图的理解。返回 `watch_for` 预警。3+ 次强模式自动提升为感知洞察。 |
-| `digest` | **上下文缓存**。存储耗时分析结果（代码库探索、API 审计）。实测节省 83% token。 |
-| `project_board` | 跨所有项目的状态看板，等同于 `/arstatus`。返回编号项目列表、待办、阻塞项。 |
-| `project_status` | 单个项目的深度状态：下一步行动、阻塞项、最近日志摘要、宫殿健康度。 |
-| `bootstrap_scan` | 扫描机器上的现有项目（git 仓库、Claude AutoMemory、CLAUDE.md）。只读，不写入。 |
-| `bootstrap_import` | 将 `bootstrap_scan` 发现的项目导入 AgentRecall。安全：不修改源文件。 |
+Run `ar --help` for the full surface · 完整命令运行 `ar --help`.
 
 ---
 
-## 记忆如何复合增长
-
-不是所有记忆都平等。五个子系统相互喂养，自动命名让索引有意义，索引让关联性成为可能，关联性让检索精准，精准检索产生有意义的反馈，反馈让下一次检索更好。
-
-**显著性评分：** `时效性(0.30) + 访问频率(0.25) + 连接数(0.20) + 紧迫性(0.15) + 重要性(0.10)`
-
-**Ebbinghaus 衰减 `R(t) = e^(−t/S)`：**
-
-| 记忆类型 | S（天） | 1天后 | 1周后 |
-|----------|---------|-------|-------|
-| 日志（情景） | 2 | 60% | ~7% |
-| 知识/Bug修复（程序） | 180 | 99% | 96% |
-| 宫殿/架构决策（语义） | 9999 | ≈100% | ≈100% |
+## Architecture · 架构
 
-旧日志噪音数天内消退，架构决策永久保留。
+TypeScript monorepo, 4 published packages · TypeScript monorepo，4 个发布包：
 
-**复合效应：**
 ```
-会话 1:    保存 3 条记忆（自动命名、索引、创建边）
-会话 10:   watch_for 在错误重复之前警告 agent
-会话 20:   感知包含 10 条交叉验证的洞察（从 40+ 条原始观察合并）
-会话 50:   Agent 了解你的优先级、盲点和沟通风格
+packages/
+├── core/          # storage + tool logic + helpers (agent-recall-core)
+├── mcp-server/    # thin MCP wrappers (agent-recall-mcp)
+├── sdk/           # programmatic API for JS/TS apps (agent-recall-sdk)
+└── cli/           # `ar` shell command (agent-recall-cli)
 ```
 
----
-
-## SDK API
+**Storage layout · 存储布局:**
 
-```typescript
-import { AgentRecall } from "agent-recall-sdk";
-const ar = new AgentRecall({ project: "my-project" });
 ```
-
-| 方法 | 说明 |
-|------|------|
-| `capture(question, answer, opts?)` | 快速问答捕获（L1 记忆） |
-| `journalWrite(content, opts?)` | 写入每日日志 |
-| `coldStart()` | 宫殿优先上下文加载（~200 token） |
-| `palaceWrite(room, content, opts?)` | 写入房间，自动扇出交叉引用 |
-| `palaceRead(room?, topic?)` | 读取房间内容 |
-| `walk(depth?, focus?)` | 渐进式宫殿漫步 |
-| `awarenessUpdate(insights, opts?)` | 复合新洞察到感知系统 |
-| `recallInsight(context, opts?)` | 跨项目洞察召回 |
-| `alignmentCheck(input)` | 记录置信度和假设 |
-| `synthesize(opts?)` | L3 合成，可选宫殿整合 |
+~/.agent-recall/
+├── projects/
+│   └── <slug>/
+│       ├── journal/                  # episodic — per-session entries
+│       ├── corrections/              # behavioral rules + outcome KPIs
+│       └── palace/
+│           ├── rooms/                # semantic — topic-clustered facts
+│           ├── skills/               # procedural — IF-THEN rules (NEW)
+│           ├── pipeline/             # narrative — project phases (NEW)
+│           ├── identity.md
+│           └── awareness             # cross-project insights
+├── dashboard.html                    # human-readable dashboard
+└── dashboard.json                    # agent-readable snapshot (NEW)
+```
+
+**Optional Supabase mirror · 可选 Supabase 镜像** — pgvector for semantic recall, RRF fusion when configured. All-local stays the default.
 
 ---
 
-## CLI 命令
+## Platform Compatibility · 平台兼容
 
-```bash
-# 日志
-ar capture <question> <answer> [--tags tag1,tag2]
-ar read [--date YYYY-MM-DD]
-ar search <query> [--include-palace]
-ar rollup [--min-age-days N] [--dry-run]
-
-# 宫殿
-ar palace write <room> <content> [--importance high|medium|low]
-ar palace walk [--depth identity|active|relevant|full]
-ar palace search <query>
-
-# 感知与洞察
-ar awareness update --insight "标题" --evidence "证据" --applies-when kw1,kw2
-ar insight <context> [--limit N]
-
-# 语义召回配置
-ar setup supabase [--migrate] [--backfill]
-
-# 全局选项
---root <path>     存储根目录（默认：~/.agent-recall）
---project <slug>  项目覆盖
-```
+| Platform | Mechanism | Status |
+|---|---|---|
+| Claude Code | MCP server + skill + hooks | ✅ Primary |
+| Cursor | MCP server | ✅ |
+| Windsurf | MCP server | ✅ |
+| VS Code (Copilot) | MCP server | ✅ |
+| Codex | MCP server | ✅ |
+| Any JS/TS app | SDK (`agent-recall-sdk`) | ✅ |
+| Terminal / CI | CLI (`ar`) | ✅ |
 
 ---
 
-## 架构
-
-### 五层记忆模型
-
-```
-L1: 工作记忆     journal_capture           「发生了什么」
-L2: 情景记忆     journal_write             「这意味着什么」
-L3: 记忆宫殿     palace_write / walk       「跨会话的知识」
-L4: 感知系统     awareness_update          「复合的洞察」
-L5: 洞察索引     recall_insight            「跨项目的经验」
-```
-
-**扇出写入** — 写入一个房间，相关房间通过 `[[wikilinks]]` 自动更新交叉引用。零 LLM 成本。
+## Docs · 文档
 
-**Obsidian 兼容** — YAML frontmatter + `[[wikilinks]]`。将 `palace/` 作为 Obsidian vault 打开即可。
+- [`UPDATE-LOG.md`](./UPDATE-LOG.md) — phase-by-phase evolution + design reasoning
+- [`REPORT-2026-05-30.html`](./REPORT-2026-05-30.html) — Phase 6 visual report
+- [`docs/`](./docs) — command reference, architecture deep-dives
+- [`SKILL.md`](./SKILL.md) — Claude Code skill definition
 
 ---
 
-## 平台兼容性
+## Community · 社区
 
-| 平台 | MCP | SDK | CLI | 说明 |
-|------|:---:|:---:|:---:|------|
-| Claude Code | ✅ | ✅ | ✅ | 完整支持 — MCP + 技能 + 命令 |
-| Cursor | ✅ | ✅ | ✅ | MCP via .cursor/mcp.json |
-| VS Code (Copilot) | ✅ | ✅ | ✅ | MCP via .vscode/mcp.json |
-| Windsurf | ✅ | ✅ | ✅ | MCP via mcp_config.json |
-| OpenAI Codex | ✅ | ✅ | ✅ | `codex mcp add` |
-| LangChain / CrewAI | — | ✅ | — | SDK 集成到你的 chain 中 |
-| Vercel AI SDK | — | ✅ | — | SDK 在 server actions 中使用 |
-| CI / GitHub Actions | — | — | ✅ | `npx agent-recall-cli` |
-| 任何 MCP 智能体 | ✅ | — | — | 标准 MCP 协议 |
+- 💬 [Telegram](https://t.me/+ywZwoHrg3AM0NDVi) — questions, feedback, requests
+- 🐛 [GitHub Issues](https://github.com/Goldentrii/AgentRecall/issues) — bugs and feature requests
+- 📦 [npm: agent-recall-mcp](https://www.npmjs.com/package/agent-recall-mcp)
+- 📦 [npm: agent-recall-sdk](https://www.npmjs.com/package/agent-recall-sdk)
+- 📦 [npm: agent-recall-cli](https://www.npmjs.com/package/agent-recall-cli)
 
 ---
 
-## 实测 Token 节省
-
-| 场景 | 无 AR | 有 AR | **节省** |
-|------|:----:|:----:|:------:|
-| **A: 简单** （2 会话，0 纠正） | 567 | 1,131 | **+99% 纯开销** |
-| **B: 中等** （5 会话，1 次纠正） | 6,220 | 4,382 | **-30%** |
-| **C: 复杂** （20 会话，5 次纠正） | 40,910 | 17,520 | **-57%** |
-| **D: 多 Agent** （3 个 agent × 5 会话） | 20,781 | 13,140 | **-37%** |
-| **E: Digest 缓存** （重复分析，1 次命中） | ~2,400 | ~400 | **-83%** |
-
-> **盈亏平衡：~3-4 个会话。** 简单一次性任务，AR 是纯开销。3+ 会话、有纠正、多 agent 的场景，AR 都能回本。
-
----
+## Contributing · 贡献
 
-## 文档
+PRs welcome. Open an issue first for anything substantive — the design is opinionated and based on published research; we want changes to be grounded the same way.
 
-| 文档 | 说明 |
-|------|------|
-| **[→ 命令参考](docs/commands.md)** | **`/arstatus`、`/arstart`、`/arsave`、`/arsaveall` 完整指南** |
-| [智能距离协议](docs/intelligent-distance-protocol.md) | 基础理论 — 人类与 AI 之间的差距是结构性的，如何减少信息损失 |
-| [评分设计原理](docs/SCORING.md) | RRF、艾宾浩斯、Beta 分布及其修复的 bug |
-| [v3.4 升级说明](UPGRADE-v3.4.md) | 语义召回、pgvector、10 工具、bootstrap、decisions 房间 |
+欢迎 PR。任何实质性改动请先开 issue——这个设计有自己的主张，且基于已发表的研究；我们希望改动也能用同样的方式落地。
 
 ---
 
-## 贡献
-
-由 [tongwu](https://github.com/Goldentrii) 在 [Novada](https://www.novada.com) 构建。
-
-- Issues & 反馈：[GitHub Issues](https://github.com/Goldentrii/AgentRecall/issues)
-- 邮箱：[tong.wu@novada.com](mailto:tong.wu@novada.com)
-
-MIT 许可证。
-
-## Star History
+## License
 
-<a href="https://www.star-history.com/?repos=Goldentrii%2FAgentRecall&type=date&legend=top-left">
- <picture>
-   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=Goldentrii/AgentRecall&type=date&theme=dark&legend=top-left" />
-   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=Goldentrii/AgentRecall&type=date&legend=top-left" />
-   <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=Goldentrii/AgentRecall&type=date&legend=top-left" />
- </picture>
-</a>
+MIT — see [LICENSE](./LICENSE).