agent-recall-mcp 3.2.3 → 3.3.2

package/README.md

@@ -1,67 +1,45 @@
 <p align="center">
   <h1 align="center">AgentRecall</h1>
-  <p align="center"><strong>The Intelligent Distance Protocol for AI Agents</strong></p>
-  <p align="center">Minimize information loss between human and AI — across every session, every agent, every project.</p>
+  <p align="center"><strong>Memory Palace for AI Agents — A Second Brain That Compounds</strong></p>
+  <p align="center">Room-based knowledge organization · Cross-project insight recall · Salience scoring · Obsidian-compatible</p>
 </p>
 
 <p align="center">
   <a href="https://www.npmjs.com/package/agent-recall-mcp"><img src="https://img.shields.io/npm/v/agent-recall-mcp?style=flat-square&color=5D34F2" alt="npm"></a>
-  <a href="https://github.com/NovadaLabs/AgentRecall/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-brightgreen?style=flat-square" alt="License"></a>
-  <img src="https://img.shields.io/badge/MCP-12_tools-orange?style=flat-square" alt="Tools">
+  <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>
+  <img src="https://img.shields.io/badge/MCP-21_tools-orange?style=flat-square" alt="Tools">
   <img src="https://img.shields.io/badge/protocol-Intelligent_Distance-5B2D8E?style=flat-square" alt="Protocol">
   <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">
 </p>
 
 ---
 
-## Intelligent Distance — The Core Idea
+## What Is AgentRecall?
 
-> *"The gap between human intelligence and AI intelligence is structural and permanent — not a temporary technology problem."*
+AgentRecall is an **MCP server** (Model Context Protocol) that gives AI agents persistent memory, cross-project insight recall, and a self-compounding awareness system. It works with Claude Code, Cursor, VS Code, Windsurf, and any MCP-compatible agent.
 
-Humans are **born** (embodied experience, emotion, survival pressure). Machines are **made** (rules, deterministic). AI is **trained** (statistical co-occurrence over data). Three different cognitive origins produce three different ways of understanding the world. This gap will not close as AI improves — because the difference is in **origin**, not capability.
-
-**The conventional approach:** make AI more human-like → close the gap.
-
-**The Intelligent Distance approach:** accept the gap as permanent → design a **protocol** that minimizes information loss when translating between the two intelligence types.
+**Not just a memory system.** Most agent memory tools store and retrieve. AgentRecall also:
+- **Organizes** knowledge into themed rooms (Memory Palace)
+- **Compounds** — insights merge and strengthen over time, not just accumulate
+- **Cross-references** — writing to one room auto-updates related rooms
+- **Recalls** — before starting a task, surfaces relevant lessons from any project
+- **Detects misunderstanding** — measures the gap between human intent and agent interpretation
 
 ```
-Human says: "click all"
-Agent hears: "click the main things"
-Gap: "all" ≠ "main things"
-
-Human says: "done means identical"
-Agent thinks: "close enough"
-Gap: "identical" ≠ "close enough"
-
-Human gives: scattered, non-linear instructions
-Agent picks: one instruction, ignores the rest
-Gap: the connective tissue between points is lost
+┌──────────────────────────────────────────────────────────────┐
+│  Layer 1: Quick Capture     journal_capture                  │
+│  Layer 2: Daily Journal     journal_write / journal_read     │
+│  Layer 3: Memory Palace     palace_write / palace_walk       │
+│  Layer 4: Awareness         awareness_update (compounding)   │
+│  Layer 5: Insight Index     recall_insight (cross-project)   │
+└──────────────────────────────────────────────────────────────┘
 ```
 
-**AgentRecall doesn't try to close this gap. It builds the protocol to navigate it.**
-
----
-
-## How AgentRecall Bridges the Gap
-
-| Intelligent Distance Gap | AgentRecall Tool | What It Does |
-|--------------------------|-----------------|-------------|
-| Agent forgets what human said yesterday | `journal_read` + `journal_cold_start` | Persistent memory — 3-layer, cache-aware |
-| Agent misunderstands human intent | `alignment_check` | Records confidence + assumptions → human corrects BEFORE work |
-| Agent contradicts a prior decision | `nudge` | Detects contradiction → surfaces it BEFORE damage |
-| Agent says "done" but human disagrees | Think-Execute-Reflect loop | Quality scoring with COUNTS ("built 11 pages, 35 tabs"), not feelings ("went well") |
-| Agent builds from imagination, not data | `journal_state` (JSON) | Structured state transfers agent-to-agent — no prose interpretation |
-| Agent repeats the same mistake | Failures section + `context_synthesize` | Cross-session pattern detection → promoted to permanent memory |
-| Next agent starts from zero | `journal_cold_start` (v3) | Hot/warm/cold cache — loads 3 files instead of 28 |
-
-**Memory solves forgetting. AgentRecall solves misunderstanding.**
-
 ---
 
 ## Quick Start
 
-### MCP Server (any agent)
-
 ```bash
 # Claude Code
 claude mcp add agent-recall -- npx -y agent-recall-mcp
@@ -71,212 +49,224 @@ claude mcp add agent-recall -- npx -y agent-recall-mcp
 
 # VS Code — .vscode/mcp.json
 { "servers": { "agent-recall": { "command": "npx", "args": ["-y", "agent-recall-mcp"] } } }
-```
 
-### Skill (Claude Code)
+# Windsurf — ~/.codeium/windsurf/mcp_config.json
+{ "mcpServers": { "agent-recall": { "command": "npx", "args": ["-y", "agent-recall-mcp"] } } }
+```
 
+**Skill (Claude Code only):**
 ```bash
 mkdir -p ~/.claude/skills/agent-recall
 curl -o ~/.claude/skills/agent-recall/SKILL.md \
-  https://raw.githubusercontent.com/NovadaLabs/AgentRecall/main/SKILL.md
+  https://raw.githubusercontent.com/Goldentrii/AgentRecall/main/SKILL.md
 ```
 
-Say **"save"** to journal. Say **"read the latest journal"** to resume.
+---
+
+## How an Agent Uses AgentRecall
+
+### Session Start
+```
+1. recall_insight(context="current task description")   → relevant cross-project insights
+2. palace_walk(depth="active")                           → project context + awareness
+```
+
+### During Work
+```
+3. alignment_check(goal="...", confidence="medium")      → verify understanding before big tasks
+4. palace_write(room="architecture", content="...")      → permanent knowledge with cross-refs
+5. journal_capture(question="...", answer="...")          → lightweight Q&A log
+```
+
+### Session End
+```
+6. journal_write(content="...", section="decisions")     → daily journal entry
+7. awareness_update(insights=[...])                       → compound into awareness system
+8. context_synthesize(consolidate=true)                   → promote journal → palace rooms
+```
 
 ---
 
-## 12 MCP Tools
+## 21 MCP Tools
+
+### Memory Palace (5 tools)
+
+| Tool | Purpose |
+|------|---------|
+| `palace_read` | Read a room or list all rooms in the Memory Palace |
+| `palace_write` | Write memory with fan-out — auto-updates cross-references via `[[wikilinks]]` |
+| `palace_walk` | Progressive cold-start: identity (~50 tok) → active (~200) → relevant (~500) → full (~2000) |
+| `palace_lint` | Health check: stale, orphan, low-salience rooms. `fix=true` to auto-archive |
+| `palace_search` | Search across all rooms, results ranked by salience score |
+
+### Awareness & Insights (2 tools)
+
+| Tool | Purpose |
+|------|---------|
+| `awareness_update` | Add insights to the compounding awareness system. Merges with existing, detects patterns |
+| `recall_insight` | Before starting work, recall cross-project insights relevant to the current task |
 
 ### Session Memory (6 tools)
 
 | Tool | Purpose |
 |------|---------|
-| `journal_read` | Read entry by date or "latest". Filter by section. |
-| `journal_write` | Write or update journal content |
-| `journal_capture` | Lightweight L1 Q&A capture |
-| `journal_list` | List recent entries |
-| `journal_search` | Full-text search across history |
+| `journal_read` | Read entry by date or "latest", with section filtering |
+| `journal_write` | Write daily journal. Optional `palace_room` for palace integration |
+| `journal_capture` | Lightweight L1 Q&A capture. Optional `palace_room` |
+| `journal_list` | List recent journal entries |
+| `journal_search` | Full-text search across history. `include_palace=true` for palace too |
 | `journal_projects` | List all tracked projects |
 
-### v3 Architecture (3 tools) — NEW
+### Architecture (3 tools)
 
 | Tool | Purpose |
 |------|---------|
-| `journal_state` | **JSON state layer** — structured read/write for agent-to-agent handoffs (milliseconds, no prose) |
-| `journal_cold_start` | **Cache-aware cold start** — HOT (today+yesterday), WARM (2-7 days), COLD (7+ days) |
-| `journal_archive` | **Archive old entries** — moves to `archive/` with summaries, keeps journal/ clean |
+| `journal_state` | JSON state layer — structured read/write for agent-to-agent handoffs |
+| `journal_cold_start` | Cache-aware cold start: HOT (0-1d) / WARM (2-7d) / COLD (7d+) |
+| `journal_archive` | Archive old entries to cold storage with summaries |
 
-### Alignment & Synthesis (3 tools)
+### Knowledge (2 tools)
 
 | Tool | Purpose |
 |------|---------|
-| `alignment_check` | Record confidence + assumptions + human corrections |
-| `nudge` | Surface contradiction between current and past input |
-| `context_synthesize` | L3 synthesis: patterns, contradictions, goal evolution |
-
----
+| `knowledge_write` | Write permanent lessons — dynamic categories, auto-creates palace rooms |
+| `knowledge_read` | Read lessons by project, category, or search query |
 
-## How Alignment Detection Works
+### Alignment (3 tools)
 
-When an agent isn't sure it understands:
+| Tool | Purpose |
+|------|---------|
+| `alignment_check` | Record confidence + assumptions → human corrects BEFORE work starts |
+| `nudge` | Detect contradiction between current and past input → surface before damage |
+| `context_synthesize` | L3 synthesis. `consolidate=true` writes results into palace rooms |
 
-```
-ALIGNMENT CHECK:
-- Goal: Build a REST API for user management
-- Confidence: medium
-- Assumptions: PostgreSQL, no auth yet, CRUD only
-- Unclear: Should this include role-based access?
-```
+---
 
-Human confirms or corrects. The delta is logged. Over time, patterns reveal where misunderstanding is most likely.
+## Architecture
 
-## How Nudge Protocol Works
+### Memory Palace
 
-When the agent detects the human contradicts a prior decision:
+Inspired by the Method of Loci, Karpathy's LLM Wiki, and nashsu/llm_wiki.
 
 ```
-NUDGE:
-- You decided Clerk for auth on March 25.
-- Now you're asking for custom auth from scratch.
-- Has the goal changed, or should we stick with Clerk?
+~/.agent-recall/
+  awareness.md                   # 200-line compounding document (global)
+  awareness-state.json           # Structured awareness data
+  insights-index.json            # Cross-project insight matching
+  projects/
+    <project>/
+      journal/                   # RAW SOURCES (immutable)
+        YYYY-MM-DD.md            # Daily journal
+        YYYY-MM-DD-log.md        # L1 captures
+        YYYY-MM-DD.state.json    # JSON state
+      palace/                    # MEMORY PALACE (mutable wiki)
+        identity.md              # ~50 token project identity card
+        palace-index.json        # Room catalog + salience scores
+        graph.json               # Cross-reference edges
+        log.md                   # Operation audit trail
+        rooms/
+          goals/                 # Active goals, evolution
+          architecture/          # Technical decisions, patterns
+          blockers/              # Current and resolved
+          alignment/             # Human corrections, misunderstandings
+          knowledge/             # Learned lessons by category
+          <custom>/              # Agents create rooms on demand
 ```
 
-Not the agent being difficult — it's helping the human **clarify their own thinking.**
+### Key Mechanisms
 
----
+**Fan-out writes** — Write to one room, cross-references auto-update in related rooms via `[[wikilinks]]`. Mechanical, zero LLM cost.
 
-## Three-Layer Memory + v3 Cache
+**Salience scoring** — Every room has a salience score: `importance(0.4) + recency(0.3) + access_frequency(0.2) + connections(0.1)`. High-salience rooms surface first. Below threshold → auto-archive.
 
-```
-┌─────────────────────────────────────────────────────────┐
-│ L1: Working Memory   [per-turn, ~50 tok]  "What happened"│
-│     ↓ synthesized into                                   │
-│ L2: Episodic Memory  [daily, ~800 tok]    "What it means"│
-│     ↓ synthesized into                                   │
-│ L3: Semantic Memory  [cross-session]      "What's true"  │
-│     (contradiction detection + goal evolution)            │
-├─────────────────────────────────────────────────────────┤
-│ v3: JSON State Layer  [per-session]  Agent-to-agent data │
-│     journal_state → .state.json alongside .md            │
-├─────────────────────────────────────────────────────────┤
-│ v3: Cache Layer       HOT (0-1d) → WARM (2-7d) → COLD   │
-│     journal_cold_start → loads 3 files, not 28           │
-└─────────────────────────────────────────────────────────┘
-```
+**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 × confirmation count.
 
-## Think-Execute-Reflect Loop
+**Obsidian-compatible** — Every palace file has YAML frontmatter + `[[wikilinks]]`. Open `palace/` as an Obsidian vault → graph view shows room connections. Zero Obsidian dependency.
 
-Every session follows a structured quality cycle:
+### Intelligent Distance Protocol
 
-```
-🧠 THINK    → Was the approach right? Was research done?
-⚡ EXECUTE  → What happened vs planned? (COUNTS, not feelings)
-🔍 REFLECT  → 5-dimension quality score + Intelligent Distance gap
-🔄 FEEDBACK → Loop (needs iteration) or Exit (quality sufficient)
-```
+The gap between human intent and agent understanding is structural — different cognitive origins, not a temporary technology problem. AgentRecall doesn't close this gap; it navigates it:
 
-**The Reflect step explicitly measures Intelligent Distance:**
-- What user meant vs what I interpreted
-- The gap between them (or "none — aligned")
-- What to change so the gap shrinks next time
+| Gap | Tool | How |
+|-----|------|-----|
+| Agent misunderstands intent | `alignment_check` | Records confidence + assumptions → human corrects before work |
+| Agent contradicts prior decision | `nudge` | Surfaces contradiction → human clarifies |
+| Agent forgets across sessions | `palace_walk` | Progressive loading from identity to full context |
+| Agent repeats past mistakes | `recall_insight` | Cross-project insights surface before work starts |
+| Agent's work quality is unclear | Think-Execute-Reflect | Counts, not feelings ("built 11 pages") |
 
 ---
 
 ## Supported Agents
 
-| Agent | Skill | MCP | Protocol |
-|-------|:-----:|:---:|:--------:|
-| Claude Code | ✅ | ✅ | ✅ |
-| Cursor | ⚡ | ✅ | ✅ |
-| VS Code Copilot | — | ✅ | ✅ |
-| Windsurf | ⚡ | ✅ | ✅ |
-| Claude Desktop | — | ✅ | ✅ |
-| Any MCP agent | — | ✅ | ✅ |
-| Any AI agent | — | — | ✅ (manual) |
+| Agent | MCP | Skill | Notes |
+|-------|:---:|:-----:|-------|
+| Claude Code | ✅ | ✅ | Full support — MCP + SKILL.md |
+| Cursor | ✅ | ⚡ | MCP via .cursor/mcp.json |
+| VS Code (Copilot) | ✅ | — | MCP via .vscode/mcp.json |
+| Windsurf | ✅ | ⚡ | MCP via mcp_config.json |
+| Claude Desktop | ✅ | — | MCP server |
+| Any MCP agent | ✅ | — | Standard MCP protocol |
 
 ---
 
-## Real Results
+## Design Philosophy
 
-Validated over **30+ sessions** across 5 production projects:
-- Cold-start: **5 min → 2 seconds** (with v3 cache: loads 3 files not 28)
-- Decision history: **0% → 100% retained** across sessions
-- Misunderstanding caught before wrong work: **6+ instances** via alignment checks
-- Quality loop caught **4 code review gaps** that would have shipped
-- Failures section prevented **3 repeated mistakes** across agent handoffs
+**Memory is not the goal. Understanding is.**
 
----
+Most memory systems optimize for retrieval accuracy. AgentRecall optimizes for **alignment accuracy** — reducing the gap between what the human means and what the agent does.
 
-## Feedback & Contributing
+**Compounding over accumulation.** A filing cabinet with better labels is still a filing cabinet. AgentRecall's awareness system forces merge-on-insert: every new insight either strengthens an existing one or replaces the weakest. After 100 sessions, `awareness.md` is still 200 lines — but each line carries the weight of confirmed, cross-validated observations.
 
-Built by [tongwu](https://github.com/Goldentrii) at [NovadaLabs](https://github.com/NovadaLabs).
+**Cross-project by default.** Insights learned in one project apply everywhere. `recall_insight` doesn't care which project produced the lesson — it matches the current situation against the global index.
 
-**We'd love your feedback:**
-
-- Email: tongwu0824@gmail.com
-- GitHub Issues: [NovadaLabs/AgentRecall](https://github.com/NovadaLabs/AgentRecall/issues)
-
-1. **Use the protocol** for a week → [report](https://github.com/NovadaLabs/AgentRecall/issues)
-2. **Implement it** in a new agent → PR welcome
-3. **Improve the spec** → [protocol doc](docs/intelligent-distance-protocol.md)
+**Agent-friendly, human-visible.** Everything is markdown on disk. Agents consume it via MCP tools. Humans browse it in Obsidian (or any text editor). Zero cloud, zero telemetry, zero lock-in.
 
 ---
 
-## License
-
-MIT — *Concept & Design: [tongwu](https://github.com/Goldentrii)*
-
-**Memory solves forgetting. AgentRecall solves misunderstanding.**
+## Real Results
 
----
+Validated over 30+ sessions across 5 production projects:
+- Cold-start: **5 min → 2 seconds** (cache-aware loading)
+- Decision retention: **0% → 100%** across sessions
+- Misunderstanding caught before wrong work: **6+ instances** via alignment checks
+- Repeated mistakes prevented: **3 instances** via cross-project insight recall
+- All data local, all files markdown, all tools stateless
 
 ---
 
-# agent-recall-mcp（中文文档）
+## Contributing
 
-> 给你的 AI 智能体一个跨会话记忆的大脑。
-
----
+Built by [tongwu](https://github.com/Goldentrii).
 
-## 智能距离（Intelligent Distance）— 核心理念
-
-> *「人类智能与 AI 智能之间的差距是结构性的、永久的 — 不是一个临时的技术问题。」*
+- Issues & feedback: [GitHub Issues](https://github.com/Goldentrii/AgentRecall/issues)
+- Email: tongwu0824@gmail.com
+- Protocol spec: [docs/intelligent-distance-protocol.md](docs/intelligent-distance-protocol.md)
 
-人类是「生出来的」（具身经验、情感、生存压力）。机器是「造出来的」（规则、确定性）。AI 是「训练出来的」（数据上的统计共现）。三种不同的认知起源，产生三种不同的理解方式。这个差距不会随 AI 进步而消失 — 因为差异在于**起源**，而非能力。
+MIT License.
 
-```
-人类说：「全部点击」
-AI 理解：「点击主要的」
-差距：「全部」≠「主要的」
+---
 
-人类说：「做完意味着完全一样」
-AI 认为：「差不多就行」
-差距：「完全一样」≠「差不多」
+---
 
-人类给出：零散、非线性的指令
-AI 选择：一条指令，忽略其余
-差距：点与点之间的逻辑关联丢失了
-```
+# AgentRecall（中文文档）
 
-**AgentRecall 不试图缩小这个差距，而是构建一个协议来导航它。**
+> 给你的 AI 智能体一个会成长的第二大脑。
 
 ---
 
-## AgentRecall 如何弥合差距
+## AgentRecall 是什么？
 
-| 智能距离缺口 | AgentRecall 工具 | 功能 |
-|-------------|-----------------|------|
-| 智能体忘了人类昨天说的话 | `journal_read` + `journal_cold_start` | 三层记忆 + 缓存感知冷启动 |
-| 智能体误解人类意图 | `alignment_check` | 记录置信度 + 假设 → 人类在工作开始前纠正 |
-| 智能体与之前的决策矛盾 | `nudge` | 检测矛盾 → 在造成损失前提出 |
-| 智能体说「完成了」但人类不同意 | Think-Execute-Reflect 循环 | 用数字评分（「建了 11 页 35 个标签」），不用感觉（「做得不错」）|
-| 智能体凭想象构建，而非基于数据 | `journal_state` (JSON) | agent 间结构化交接 — 毫秒级，无需解析散文 |
-| 智能体重复同样的错误 | 失败记录 + `context_synthesize` | 跨会话模式检测 → 提升为永久记忆 |
-| 下一个 agent 从零开始 | `journal_cold_start` (v3) | 热/温/冷缓存 — 加载 3 个文件而非 28 个 |
+AgentRecall 是一个 **MCP 服务器**（Model Context Protocol），为 AI 智能体提供持久化记忆、跨项目洞察召回和自复合感知系统。支持 Claude Code、Cursor、VS Code、Windsurf 及所有 MCP 兼容的智能体。
 
-**记忆解决遗忘，AgentRecall 解决误解。**
+**不只是记忆系统。** 大多数智能体记忆工具只做存储和检索。AgentRecall 还能：
+- **组织** — 知识按主题房间分类（记忆宫殿）
+- **复合** — 洞察随时间合并增强，不是单纯累积
+- **交叉引用** — 写入一个房间时自动更新相关房间
+- **召回** — 开始任务前，自动呈现任何项目中的相关经验教训
+- **检测误解** — 测量人类意图和智能体理解之间的差距
 
 ---
 
@@ -293,85 +283,153 @@ claude mcp add agent-recall -- npx -y agent-recall-mcp
 { "servers": { "agent-recall": { "command": "npx", "args": ["-y", "agent-recall-mcp"] } } }
 ```
 
+**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
+```
+
+---
+
+## 智能体使用流程
+
+### 会话开始
+```
+1. recall_insight(context="当前任务描述")    → 跨项目相关洞察
+2. palace_walk(depth="active")               → 项目上下文 + 感知摘要
+```
+
+### 工作中
+```
+3. alignment_check(goal="...", confidence="medium")   → 大任务前确认理解
+4. palace_write(room="architecture", content="...")   → 永久知识 + 交叉引用
+5. journal_capture(question="...", answer="...")       → 轻量问答记录
+```
+
+### 会话结束
+```
+6. journal_write(content="...", section="decisions")  → 每日日志
+7. awareness_update(insights=[...])                    → 洞察复合到感知系统
+8. context_synthesize(consolidate=true)                → 日志内容提升到宫殿
+```
+
 ---
 
-## 12 个工具
+## 21 个 MCP 工具
+
+### 记忆宫殿（5 个）
+
+| 工具 | 功能 |
+|------|------|
+| `palace_read` | 读取房间内容或列出所有房间 |
+| `palace_write` | 写入记忆，自动通过 `[[wikilinks]]` 扇出交叉引用 |
+| `palace_walk` | 渐进式冷启动：identity (~50 tok) → active (~200) → relevant (~500) → full (~2000) |
+| `palace_lint` | 健康检查：过期、孤立、低显著性房间。`fix=true` 自动归档 |
+| `palace_search` | 全房间搜索，按显著性评分排序 |
+
+### 感知与洞察（2 个）
+
+| 工具 | 功能 |
+|------|------|
+| `awareness_update` | 添加洞察到复合感知系统。自动合并相似洞察，检测跨洞察模式 |
+| `recall_insight` | 开始任务前，召回跨项目的相关洞察 |
 
 ### 会话记忆（6 个）
 
 | 工具 | 功能 |
 |------|------|
 | `journal_read` | 按日期读取日志，支持章节过滤 |
-| `journal_write` | 追加或替换今日日志 |
+| `journal_write` | 写入每日日志。可选 `palace_room` 同步到宫殿 |
 | `journal_capture` | 轻量问答捕获 |
 | `journal_list` | 列出最近日志 |
-| `journal_search` | 全文搜索 |
+| `journal_search` | 全文搜索。`include_palace=true` 同时搜索宫殿 |
 | `journal_projects` | 列出所有项目 |
 
-### v3 架构（3 个）— 新增
+### 架构工具（3 个）
 
 | 工具 | 功能 |
 |------|------|
-| `journal_state` | **JSON 状态层** — 结构化读写，agent 间毫秒级交接 |
-| `journal_cold_start` | **缓存感知冷启动** — 热（0-1天）/ 温（2-7天）/ 冷（7天+） |
-| `journal_archive` | **归档旧条目** — 移至 archive/，保留单行摘要 |
+| `journal_state` | JSON 状态层 — agent 间毫秒级结构化交接 |
+| `journal_cold_start` | 缓存感知冷启动：热 (0-1天) / 温 (2-7天) / 冷 (7天+) |
+| `journal_archive` | 归档旧条目到冷存储 |
 
-### 对齐 & 合成（3 个）
+### 知识工具（2 个）
 
 | 工具 | 功能 |
 |------|------|
-| `alignment_check` | 记录理解度、置信度、假设、人类纠正 |
-| `nudge` | 检测矛盾，主动提问 |
-| `context_synthesize` | 跨会话合成：目标演变、决策历史、模式检测 |
+| `knowledge_write` | 写入永久教训 — 动态类别，自动创建宫殿房间 |
+| `knowledge_read` | 按项目、类别或搜索词读取教训 |
+
+### 对齐工具（3 个）
+
+| 工具 | 功能 |
+|------|------|
+| `alignment_check` | 记录置信度 + 假设 → 人类在工作前纠正 |
+| `nudge` | 检测与过去决策的矛盾 → 在造成损失前提出 |
+| `context_synthesize` | L3 合成。`consolidate=true` 将结果写入宫殿房间 |
 
 ---
 
-## 三层记忆 + v3 缓存
+## 架构
+
+### 五层记忆模型
 
 ```
-┌─────────────────────────────────────────────────────────┐
-│ L1: 工作记忆    [每轮, ~50 tok]     「发生了什么」        │
-│     ↓ 合成为                                             │
-│ L2: 情景记忆    [每日日志, ~800 tok] 「这意味着什么」      │
-│     ↓ 合成为                                             │
-│ L3: 语义记忆    [跨会话]            「跨会话的真相」       │
-│     （矛盾检测 + 目标演变追踪）                           │
-├─────────────────────────────────────────────────────────┤
-│ v3: JSON 状态层  [每会话]  agent 间结构化数据              │
-├─────────────────────────────────────────────────────────┤
-│ v3: 缓存层       热（0-1天）→ 温（2-7天）→ 冷（7天+）    │
-│     journal_cold_start → 加载 3 个文件而非 28 个          │
-└─────────────────────────────────────────────────────────┘
+┌──────────────────────────────────────────────────────────────┐
+│  L1: 工作记忆     journal_capture          「发生了什么」     │
+│  L2: 情景记忆     journal_write            「这意味着什么」   │
+│  L3: 记忆宫殿     palace_write / walk      「跨会话的知识」   │
+│  L4: 感知系统     awareness_update          「复合的洞察」     │
+│  L5: 洞察索引     recall_insight            「跨项目的经验」   │
+└──────────────────────────────────────────────────────────────┘
 ```
 
----
+### 核心机制
 
-## Think-Execute-Reflect 质量循环
+**扇出写入** — 写入一个房间，相关房间通过 `[[wikilinks]]` 自动更新交叉引用。机械式处理，零 LLM 成本。
 
-```
-🧠 THINK    → 方法对吗？做了调研吗？
-⚡ EXECUTE  → 实际 vs 计划？（用数字，不用感觉）
-🔍 REFLECT  → 5 维度质量评分 + 智能距离差距分析
-🔄 FEEDBACK → 循环（需要迭代）或 退出（质量足够）
-```
+**显著性评分** — 每个房间有显著性分数：`重要性(0.4) + 时效性(0.3) + 访问频率(0.2) + 连接数(0.1)`。高显著性房间优先展示，低于阈值自动归档。
+
+**复合感知** — `awareness.md` 上限 200 行。新洞察加入时，相似的合并（增强），不相似的竞争（最低确认次数的被替换）。约束创造压缩，压缩创造复合。
+
+**跨项目洞察召回** — `insights-index.json` 通过关键词将洞察映射到场景。`recall_insight("构建质量检查")` 返回来自任何项目的相关教训。
+
+**Obsidian 兼容** — 每个宫殿文件都有 YAML frontmatter + `[[wikilinks]]`。将 `palace/` 作为 Obsidian vault 打开 → 图形视图展示房间连接。零 Obsidian 依赖。
 
-**Reflect 步骤显式测量智能距离：**
-- 用户意图 vs 我的理解
-- 两者之间的差距（或「无 — 已对齐」）
-- 下次如何缩小差距
+### 智能距离协议
+
+人类意图与智能体理解之间的差距是结构性的 — 源于不同的认知起源，不是临时的技术问题。
+
+| 差距 | 工具 | 机制 |
+|------|------|------|
+| 智能体误解意图 | `alignment_check` | 记录置信度 + 假设 → 人类在工作前纠正 |
+| 智能体与先前决策矛盾 | `nudge` | 发现矛盾 → 人类澄清 |
+| 智能体跨会话遗忘 | `palace_walk` | 从身份到完整上下文的渐进式加载 |
+| 智能体重复过去的错误 | `recall_insight` | 跨项目洞察在工作前自动呈现 |
 
 ---
 
-## 反馈 & 贡献
+## 设计理念
 
-由 [tongwu](https://github.com/Goldentrii) 在 [NovadaLabs](https://github.com/NovadaLabs) 构建。
+**记忆不是目的，理解才是。**
 
-**我们期待你的反馈：**
-- 邮箱：tongwu0824@gmail.com
-- GitHub Issues：[NovadaLabs/AgentRecall](https://github.com/NovadaLabs/AgentRecall/issues)
+大多数记忆系统优化检索准确性。AgentRecall 优化**对齐准确性** — 缩小人类意图和智能体行为之间的差距。
+
+**复合优于累积。** 贴了更好标签的文件柜还是文件柜。AgentRecall 的感知系统在插入时强制合并：每个新洞察要么增强已有的，要么替换最弱的。100 个会话后，`awareness.md` 仍是 200 行 — 但每一行承载着经过确认和交叉验证的观察。
+
+**默认跨项目。** 在一个项目中学到的洞察适用于所有项目。`recall_insight` 不关心教训来自哪个项目 — 它匹配当前场景和全局索引。
+
+**智能体友好，人类可见。** 一切都是磁盘上的 markdown。智能体通过 MCP 工具消费。人类在 Obsidian（或任何文本编辑器）中浏览。零云端、零遥测、零锁定。
 
 ---
 
-## 许可证
+## 贡献
+
+由 [tongwu](https://github.com/Goldentrii) 构建。
+
+- Issues & 反馈：[GitHub Issues](https://github.com/Goldentrii/AgentRecall/issues)
+- 邮箱：tongwu0824@gmail.com
+- 协议规范：[docs/intelligent-distance-protocol.md](docs/intelligent-distance-protocol.md)
 
-MIT — [tongwu](https://github.com/Goldentrii) @ [NovadaLabs](https://github.com/NovadaLabs)
+MIT 许可证。