npm - agent-recall-mcp - Versions diffs - 3.3.1 → 3.3.2 - Mend

agent-recall-mcp 3.3.1 → 3.3.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/README.md CHANGED Viewed

@@ -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-14_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,321 +49,387 @@ 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
+```
 ---
-## 14 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 |
-### Knowledge Loop (2 tools) — NEW
+### Knowledge (2 tools)
 | Tool | Purpose |
 |------|---------|
-| `knowledge_write` | **Write permanent lessons** — structured entries by category (extraction, build, verification, tools, general). Agents learn from past mistakes. |
-| `knowledge_read` | **Read past lessons** — filter by project, category, or search query. Agents check what went wrong before starting work. |
+| `knowledge_write` | Write permanent lessons — dynamic categories, auto-creates palace rooms |
+| `knowledge_read` | Read lessons by project, category, or search query |
-### Alignment & Synthesis (3 tools)
+### Alignment (3 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 |
+| `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 |
 ---
-## How Alignment Detection Works
+## Architecture
-When an agent isn't sure it understands:
+### Memory Palace
+Inspired by the Method of Loci, Karpathy's LLM Wiki, and nashsu/llm_wiki.
 ```
-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?
+~/.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
 ```
-Human confirms or corrects. The delta is logged. Over time, patterns reveal where misunderstanding is most likely.
+### Key Mechanisms
-## How Nudge Protocol Works
+**Fan-out writes** — Write to one room, cross-references auto-update in related rooms via `[[wikilinks]]`. Mechanical, zero LLM cost.
-When the agent detects the human contradicts a prior decision:
+**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.
-```
-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?
-```
+**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.
-Not the agent being difficult — it's helping the human **clarify their own thinking.**
+**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.
----
+**Obsidian-compatible** — Every palace file has YAML frontmatter + `[[wikilinks]]`. Open `palace/` as an Obsidian vault → graph view shows room connections. Zero Obsidian dependency.
-## Three-Layer Memory + v3 Cache
+### Intelligent Distance Protocol
-```
-┌─────────────────────────────────────────────────────────┐
-│ 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           │
-└─────────────────────────────────────────────────────────┘
-```
+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:
+| 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") |
 ---
-## Think-Execute-Reflect Loop
+## Supported Agents
-Every session follows a structured quality cycle:
+| 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 |
-```
-🧠 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 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
+## Design Philosophy
----
+**Memory is not the goal. Understanding is.**
-## Supported Agents
+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.
+**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.
+**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.
-| Agent | Skill | MCP | Protocol |
-|-------|:-----:|:---:|:--------:|
-| Claude Code | ✅ | ✅ | ✅ |
-| Cursor | ⚡ | ✅ | ✅ |
-| VS Code Copilot | — | ✅ | ✅ |
-| Windsurf | ⚡ | ✅ | ✅ |
-| Claude Desktop | — | ✅ | ✅ |
-| Any MCP agent | — | ✅ | ✅ |
-| Any AI agent | — | — | ✅ (manual) |
+**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.
 ---
 ## Real Results
-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
+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
-- Quality loop caught **4 code review gaps** that would have shipped
-- Failures section prevented **3 repeated mistakes** across agent handoffs
+- Repeated mistakes prevented: **3 instances** via cross-project insight recall
+- All data local, all files markdown, all tools stateless
 ---
-## Feedback & Contributing
+## Contributing
-Built by [tongwu](https://github.com/Goldentrii) at [NovadaLabs](https://github.com/NovadaLabs).
-**We'd love your feedback:**
+Built by [tongwu](https://github.com/Goldentrii).
+- Issues & feedback: [GitHub Issues](https://github.com/Goldentrii/AgentRecall/issues)
 - Email: tongwu0824@gmail.com
-- GitHub Issues: [NovadaLabs/AgentRecall](https://github.com/NovadaLabs/AgentRecall/issues)
+- Protocol spec: [docs/intelligent-distance-protocol.md](docs/intelligent-distance-protocol.md)
-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)
+MIT License.
 ---
-## License
+---
-MIT — *Concept & Design: [tongwu](https://github.com/Goldentrii)*
+# AgentRecall（中文文档）
-**Memory solves forgetting. AgentRecall solves misunderstanding.**
+> 给你的 AI 智能体一个会成长的第二大脑。
 ---
----
+## AgentRecall 是什么？
-# agent-recall-mcp（中文文档）
+AgentRecall 是一个 **MCP 服务器**（Model Context Protocol），为 AI 智能体提供持久化记忆、跨项目洞察召回和自复合感知系统。支持 Claude Code、Cursor、VS Code、Windsurf 及所有 MCP 兼容的智能体。
-> 给你的 AI 智能体一个跨会话记忆的大脑。
+**不只是记忆系统。** 大多数智能体记忆工具只做存储和检索。AgentRecall 还能：
+- **组织** — 知识按主题房间分类（记忆宫殿）
+- **复合** — 洞察随时间合并增强，不是单纯累积
+- **交叉引用** — 写入一个房间时自动更新相关房间
+- **召回** — 开始任务前，自动呈现任何项目中的相关经验教训
+- **检测误解** — 测量人类意图和智能体理解之间的差距
 ---
-## 智能距离（Intelligent Distance）— 核心理念
+## 快速开始
-> *「人类智能与 AI 智能之间的差距是结构性的、永久的 — 不是一个临时的技术问题。」*
+```bash
+# Claude Code
+claude mcp add agent-recall -- npx -y agent-recall-mcp
-人类是「生出来的」（具身经验、情感、生存压力）。机器是「造出来的」（规则、确定性）。AI 是「训练出来的」（数据上的统计共现）。三种不同的认知起源，产生三种不同的理解方式。这个差距不会随 AI 进步而消失 — 因为差异在于**起源**，而非能力。
+# Cursor — .cursor/mcp.json
+{ "mcpServers": { "agent-recall": { "command": "npx", "args": ["-y", "agent-recall-mcp"] } } }
+# VS Code — .vscode/mcp.json
+{ "servers": { "agent-recall": { "command": "npx", "args": ["-y", "agent-recall-mcp"] } } }
 ```
-人类说：「全部点击」
-AI 理解：「点击主要的」
-差距：「全部」≠「主要的」
-人类说：「做完意味着完全一样」
-AI 认为：「差不多就行」
-差距：「完全一样」≠「差不多」
-人类给出：零散、非线性的指令
-AI 选择：一条指令，忽略其余
-差距：点与点之间的逻辑关联丢失了
+**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
 ```
-**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 个 |
+### 会话开始
+```
+1. recall_insight(context="当前任务描述")    → 跨项目相关洞察
+2. palace_walk(depth="active")               → 项目上下文 + 感知摘要
+```
-**记忆解决遗忘，AgentRecall 解决误解。**
+### 工作中
+```
+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)                → 日志内容提升到宫殿
+```
 ---
-## 快速开始
+## 21 个 MCP 工具
-```bash
-# Claude Code
-claude mcp add agent-recall -- npx -y agent-recall-mcp
+### 记忆宫殿（5 个）
-# Cursor — .cursor/mcp.json
-{ "mcpServers": { "agent-recall": { "command": "npx", "args": ["-y", "agent-recall-mcp"] } } }
-# VS Code — .vscode/mcp.json
-{ "servers": { "agent-recall": { "command": "npx", "args": ["-y", "agent-recall-mcp"] } } }
-```
+| 工具 | 功能 |
+|------|------|
+| `palace_read` | 读取房间内容或列出所有房间 |
+| `palace_write` | 写入记忆，自动通过 `[[wikilinks]]` 扇出交叉引用 |
+| `palace_walk` | 渐进式冷启动：identity (~50 tok) → active (~200) → relevant (~500) → full (~2000) |
+| `palace_lint` | 健康检查：过期、孤立、低显著性房间。`fix=true` 自动归档 |
+| `palace_search` | 全房间搜索，按显著性评分排序 |
----
+### 感知与洞察（2 个）
-## 14 个工具
+| 工具 | 功能 |
+|------|------|
+| `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` | 归档旧条目到冷存储 |
-### 知识循环（2 个）— 新增
+### 知识工具（2 个）
 | 工具 | 功能 |
 |------|------|
-| `knowledge_write` | **写入永久教训** — 按类别结构化记录（提取、构建、验证、工具、通用）。Agent 从过去的错误中学习。 |
-| `knowledge_read` | **读取过去教训** — 按项目、类别或搜索词过滤。Agent 开始工作前检查过去的失败。 |
+| `knowledge_write` | 写入永久教训 — 动态类别，自动创建宫殿房间 |
+| `knowledge_read` | 按项目、类别或搜索词读取教训 |
-### 对齐 & 合成（3 个）
+### 对齐工具（3 个）
 | 工具 | 功能 |
 |------|------|
-| `alignment_check` | 记录理解度、置信度、假设、人类纠正 |
-| `nudge` | 检测矛盾，主动提问 |
-| `context_synthesize` | 跨会话合成：目标演变、决策历史、模式检测 |
+| `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)`。高显著性房间优先展示，低于阈值自动归档。
-**Reflect 步骤显式测量智能距离：**
-- 用户意图 vs 我的理解
-- 两者之间的差距（或「无 — 已对齐」）
-- 下次如何缩小差距
+**复合感知** — `awareness.md` 上限 200 行。新洞察加入时，相似的合并（增强），不相似的竞争（最低确认次数的被替换）。约束创造压缩，压缩创造复合。
+**跨项目洞察召回** — `insights-index.json` 通过关键词将洞察映射到场景。`recall_insight("构建质量检查")` 返回来自任何项目的相关教训。
+**Obsidian 兼容** — 每个宫殿文件都有 YAML frontmatter + `[[wikilinks]]`。将 `palace/` 作为 Obsidian vault 打开 → 图形视图展示房间连接。零 Obsidian 依赖。
+### 智能距离协议
+人类意图与智能体理解之间的差距是结构性的 — 源于不同的认知起源，不是临时的技术问题。
+| 差距 | 工具 | 机制 |
+|------|------|------|
+| 智能体误解意图 | `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 许可证。

package/dist/types.d.ts CHANGED Viewed

@@ -1,7 +1,7 @@
 /**
  * Shared types, interfaces, and constants for agent-recall-mcp.
  */
-export declare const VERSION = "3.3.1";
+export declare const VERSION = "3.3.2";
 export declare const JOURNAL_ROOT: string;
 export declare const LEGACY_ROOT: string;
 export declare const SECTION_HEADERS: Record<string, string>;

package/dist/types.js CHANGED Viewed

@@ -6,7 +6,7 @@ import * as os from "node:os";
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
-export const VERSION = "3.3.1";
+export const VERSION = "3.3.2";
 export const JOURNAL_ROOT = process.env.AGENT_RECALL_ROOT || path.join(os.homedir(), ".agent-recall");
 export const LEGACY_ROOT = path.join(os.homedir(), ".claude", "projects");
 export const SECTION_HEADERS = {

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "agent-recall-mcp",
-  "version": "3.3.1",
+  "version": "3.3.2",
   "description": "Memory Palace for AI agents — room-based knowledge organization with fan-out cross-referencing, salience scoring, and Obsidian-compatible output",
   "type": "module",
   "main": "dist/index.js",