agent-recall-mcp 3.3.14 → 3.3.15

package/README.md

@@ -1,16 +1,23 @@
 <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">Persistent, compounding memory + Intelligent Distance Protocol. MCP server + SDK + CLI.</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">Persistent, compounding memory + automatic correction capture. MCP server + SDK + CLI.</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&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>
-  <img src="https://img.shields.io/badge/MCP-22_tools-orange?style=flat-square" alt="Tools">
+  <img src="https://img.shields.io/badge/MCP-5_tools-orange?style=flat-square" alt="Tools">
   <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/overhead-~876_tokens%2Fsession-22C55E?style=flat-square" alt="Token overhead">
+  <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_(1885)-3B82F6?style=flat-square" alt="Ebbinghaus decay">
+  <img src="https://img.shields.io/badge/feedback-Bayesian_Beta-F59E0B?style=flat-square" alt="Beta distribution">
 </p>
 
 <p align="center">
@@ -19,18 +26,18 @@
   <a href="#three-ways-to-use-it">Use</a> ·
   <a href="#what-is-agentrecall">What</a> ·
   <a href="#quick-start">Install</a> ·
-  <a href="#22-mcp-tools">Tools</a> ·
+  <a href="#5-mcp-tools">Tools</a> ·
+  <a href="#how-memory-compounds">Compounding</a> ·
   <a href="#sdk-api">SDK</a> ·
-  <a href="#cli-commands">CLI</a> ·
   <a href="#architecture">Architecture</a> ·
   <a href="#docs">Docs</a>
   &nbsp;&nbsp;|&nbsp;&nbsp;
   <b>中文:</b>&nbsp;
   <a href="#agentrecall中文文档">简介</a> ·
   <a href="#快速开始">安装</a> ·
-  <a href="#22-个-mcp-工具">工具</a> ·
+  <a href="#5-个-mcp-工具">工具</a> ·
+  <a href="#记忆如何复合增长">复合</a> ·
   <a href="#sdk-api-1">SDK</a> ·
-  <a href="#cli-命令">CLI</a> ·
   <a href="#架构">架构</a>
 </p>
 
@@ -40,6 +47,18 @@
   <a href="#arsave-and-arstart"><img src="https://img.shields.io/badge/%2Farsave-Save_Session-FF6B6B?style=for-the-badge" alt="/arsave"></a>
   <a href="#arsave-and-arstart"><img src="https://img.shields.io/badge/%2Farstart-Load_Context-4ECDC4?style=for-the-badge" alt="/arstart"></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>
 
 ## `/arsave` and `/arstart`
 
@@ -73,6 +92,14 @@ Day 2: "What monorepo?"               Day 2: /arstart
   → Misses half the tasks                → Pushes to both repos
 ```
 
+### Three Layers of Value
+
+**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.
+
+**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.
+
 ### Real Session Flow
 
 This is from an actual multi-day project where a human gave scattered, non-linear instructions. The agent used AgentRecall throughout:
@@ -83,35 +110,35 @@ Session 1 (Tuesday)                          Session 2 (Wednesday, different age
 
 /arstart                                     /arstart
   │                                            │
-  ├─ palace_walk ──→ "monorepo project,        ├─ palace_walk ──→ loads Tuesday's
-  │                   SDK + CLI planned"        │                  architecture decisions
-  │                                            │                  in 200 tokens
-  ├─ recall_insight ──→ 3 prior lessons        ├─ recall_insight
-  │   • "structurize scattered input"          │   • "no version inflation"
-  │   • "search before building"               │   • "arsave/arstart = hero section"
-  │   • "ask when ambiguous"                   │
-  │                                            ├─ Continues exactly where
-  ▼                                            │  Session 1 left off
-Human: "we need SDK, CLI,                     │
-  update README, fix versions"                 ▼
-  │                                           Human: "publish to npm,
-  ├─ alignment_check                            update both GitHub repos"
-  │   confidence: medium                        │
-  │   4 tasks detected                          ├─ No re-explanation needed.
-  │   → present plan → human confirms           │   Agent already knows the
-  │                                             │   monorepo structure, package
-  ├─ Execute in order:                          │   names, and version policy.
-  │   1. Core extraction ✓                      │
-  │   2. Tool logic split ✓                     └─ Done in 2 minutes
-  │   3. MCP wrappers ✓                             (vs 20 min cold start
-  │   4. SDK + CLI ✓                                  without AgentRecall)
+  ├─ session_start() ──→ identity,             ├─ session_start() ──→ loads Tuesday's
+  │   top insights, active rooms,              │   decisions in ~400 tokens,
+  │   cross-project matches,                   │   watch_for: "structurize input"
+  │   watch_for warnings                       │
+  │                                            ├─ recall("SDK CLI monorepo") ──→
+  ├─ recall("SDK CLI versions") ──→            │   • "no version inflation"
+  │   • "structurize scattered input"          │   • "arsave/arstart = hero section"
+  │   • "search before building"               │
+  │   • "ask when ambiguous"                   ├─ Continues exactly where
+  │                                            │  Session 1 left off
+  ▼                                            │
+Human: "we need SDK, CLI,                     ▼
+  update README, fix versions"               Human: "publish to npm,
+  │                                           update both GitHub repos"
+  ├─ check(goal="SDK+CLI+README",             │
+  │   confidence="medium")                    ├─ No re-explanation needed.
+  │   → 4 tasks detected                      │   Agent already knows the
+  │   → present plan → human confirms         │   monorepo structure, package
+  │                                           │   names, and version policy.
+  ├─ Execute in order:                        │
+  │   1. Core extraction ✓                    └─ Done in 2 minutes
+  │   2. Tool logic split ✓                       (vs 20 min cold start
+  │   3. MCP wrappers ✓                             without AgentRecall)
+  │   4. SDK + CLI ✓
   │
 /arsave
   │
-  ├─ journal_write ──→ decisions + tasks saved
-  ├─ awareness_update ──→ "scattered input →
-  │                        structurize → confirm"
-  └─ palace_write ──→ architecture room updated
+  └─ session_end(summary, insights, trajectory)
+       → journal + awareness + palace — one call
 ```
 
 ---
@@ -304,81 +331,171 @@ ar rollup --min-age-days 14
 
 ## 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`)
 ```
-1. recall_insight(context="current task description")   → relevant cross-project insights
-2. palace_walk(depth="active")                           → project context + awareness
+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
 ```
-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
+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
+### Session End (`/arsave`)
 ```
-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
+session_end(summary="...", insights=[...], trajectory="...")  → journal + awareness + consolidation
 ```
 
 ---
 
-## 22 MCP Tools
+## 5 MCP Tools
 
-### Memory Palace (5 tools)
+AgentRecall exposes exactly 5 tools to agents. Each tool composes multiple subsystems internally — the agent doesn't need to know about the plumbing.
 
-| 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 |
+| 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. |
 
-### Awareness & Insights (2 tools)
+### Legacy 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 |
+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.
 
-### Session Memory (6 tools)
+---
 
-| Tool | Purpose |
-|------|---------|
-| `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 |
+## How Memory Compounds
 
-### Architecture (4 tools)
+<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>
 
-| Tool | Purpose |
-|------|---------|
-| `journal_state` | JSON state layer — structured read/write for agent-to-agent handoffs |
-| `journal_cold_start` | Palace-first cold start: loads identity + awareness + top rooms (~200 tok), then HOT journals only |
-| `journal_archive` | Archive old entries to cold storage with summaries |
-| `journal_rollup` | Condense old daily journals into weekly summaries. Prevents accumulation. `dry_run=true` to preview |
+> 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. After 10 sessions, the system knows more than any individual memory contains.
 
-### Knowledge (2 tools)
+### 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"`.
+
+```
+Content: "Fixed a critical bug where the payment processor crashed on refunds"
+  → Type detected: bug-fix
+  → Keywords extracted: payment, processor, crashed, refunds
+  → Slug generated: bug-fix-payment-processor-crashed
+```
+
+Good naming IS the first layer of retrieval. A well-named memory is 80% findable without any search algorithm.
+
+### 2. Indexes
+
+Every memory has an address in three index systems:
+
+| 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, but each line carries cross-validated weight |
+
+Indexes are cheap pointers. The agent scans indexes first, then loads full content only when needed.
+
+### 3. Relativity
+
+Memories that relate to each other are connected automatically — no wikilinks needed.
+
+```
+Agent writes: "JWT refresh rotation prevents session fixation"
+  → Keywords: jwt, refresh, rotation, session
+  → Room "architecture" has tags: ["technical"]
+  → Room "knowledge" has a lesson about "session management"
+  → Auto-edge created: architecture ←→ knowledge (weight 0.3)
+```
 
-| Tool | Purpose |
-|------|---------|
-| `knowledge_write` | Write permanent lessons — dynamic categories, auto-creates palace rooms |
-| `knowledge_read` | Read lessons by project, category, or search query |
+When you `recall("session security")`, the system surfaces keyword-matched memories across connected rooms. Edges are stored in `graph.json` and are available for traversal — relativity turns isolated memories into a knowledge graph.
 
-### Alignment (3 tools)
+### 4. Weight + Decay
 
-| 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 |
+Not all memories are equal. Salience scoring ensures the right memory surfaces first:
+
+```
+salience = recency(0.30) + access(0.25) + connections(0.20) + urgency(0.15) + importance(0.10)
+```
+
+- Architecture decisions decay at 0.98/day (persistent). Blockers decay at 0.90/day (ephemeral).
+- Memories you actually access get stronger. Memories you never revisit fade.
+- Demoted insights don't die — they go to the archive. If a future insight matches, they resurrect.
+
+`recall` applies the **Ebbinghaus forgetting curve** `R(t) = e^(−t/S)` with memory-type-specific strength values — matching the psychological reality of each type:
+
+| 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. Same query, right results.
+
+### 5. Feedback Loop
+
+The system learns what's useful and what's not, using a **Bayesian Beta distribution** — the mathematically optimal estimate of true usefulness from binary observations (`E[Beta(α,β)] = (pos+1)/(pos+neg+2)`):
+
+```
+Session 1: recall("auth design") → returns 5 results
+  Agent rates: result #1 useful, result #3 not useful
+  → Stored in feedback-log.json with query context
+
+Session 2: recall("auth patterns") → similar query
+  → Result #1: Beta(2,1) → E[U]=0.67 → ×1.33 score multiplier
+  → Result #3: Beta(1,2) → E[U]=0.33 → ×0.67 score multiplier
+  → Rankings shift: useful memories rise, noise sinks
+```
+
+No-feedback items stay neutral (multiplier ×1.0). Feedback is query-aware — rating a result "useless" for "auth design" doesn't penalize it for "database schema". The system learns per-context, not globally.
+
+### 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
+```
+
+Each layer multiplies the others. Auto-naming makes indexing useful. Indexing makes relativity possible. Relativity makes recall precise. Precise recall generates meaningful feedback. Feedback makes the next recall even better. The loop compounds.
 
 ---
 
@@ -458,7 +575,7 @@ await memory.awarenessUpdate([{
 The `agent-recall-cli` package provides the `ar` command for terminal workflows, CI pipelines, and quick access to your agent's memory outside of an editor.
 
 ```
-ar v3.3.4 — AgentRecall CLI
+ar v3.3.14 — AgentRecall CLI
 
 JOURNAL:
   ar read [--date YYYY-MM-DD] [--section <name>]
@@ -491,6 +608,11 @@ META:
   ar knowledge write --category <cat> --title "t" --what "w" --cause "c" --fix "f"
   ar knowledge read [--category <cat>]
 
+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
@@ -528,17 +650,21 @@ L5: Insight Index      recall_insight            "cross-project experience"
 ~/.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
   projects/
     <project>/
       journal/
         YYYY-MM-DD.md             # Daily journal
-        YYYY-MM-DD-log.md         # L1 captures
+        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
+        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
@@ -571,12 +697,53 @@ L5: Insight Index      recall_insight            "cross-project experience"
 
 ## Real Results
 
-Validated over 30+ sessions across 5 production projects:
-- Cold-start: **5 min → 2 seconds** (cache-aware loading)
+Validated over 42+ sessions across 5 production projects:
+- Cold-start: **5 min → 2 seconds** (palace-first loading, ~400 tokens)
 - Decision retention: **0% → 100%** across sessions
-- Misunderstanding caught before wrong work: **6+ instances** via alignment checks
+- Misunderstanding caught before wrong work: **6+ instances** via `check` before publish/deploy
 - Repeated mistakes prevented: **3 instances** via cross-project insight recall
-- All data local, all files markdown, all tools stateless
+
+### Measured Token Cost (v3.3.14, 5 rounds)
+
+| Surface | What it returns | Measured tokens |
+|---------|----------------|-----------------|
+| `hook-start` (stdout) | identity + watch_for + 3 insights + recent + cross-project hint | ~215 |
+| `session_start` (MCP) | full session context — all fields | ~601 |
+| `check` (MCP) | watch_for patterns + past deltas | ~80 |
+| **Total session overhead** | | **~896 tokens** |
+
+Each prevented correction ≈ **1,500 tokens saved** (re-explanation + wrong work + retry).  
+Breakeven: **less than 1 correction prevented per session** covers the overhead.  
+At 42 sessions with avg 1.5 corrections prevented: **~94,000 tokens saved** vs ~37,600 overhead.
+
+### What the 5 Test Rounds Verified
+
+**Round 1 — hook-start:**  
+Fires on session open (with per-session lock to avoid double-fire). Output: project identity, past correction warnings (watch_for), top 3 awareness insights, today's journal brief, cross-project hint. All in 9 lines.
+
+**Round 2 — capture / palace write / search / walk:**  
+- `capture "bug fix"` → routes to journal log with auto-tags
+- `palace write architecture "..."` → writes to room with fan-out
+- `search "journal crash fix"` → keyword match finds the entry from 2 minutes ago
+- `palace walk --depth active` → loads 5 rooms, top 10 insights, architecture decisions in one JSON
+
+**Round 3 — hook-correction / hook-end / MCP tools:**  
+- `hook-correction` with no-correction prompt → silent exit (correct)
+- `hook-correction` with correction ("no use patch not minor") → silent capture, exit 0
+- `hook-end` → exit 0, auto-log entry
+- MCP `session_start` → 601 tokens, all 7 fields populated
+- MCP `check(goal="publish v3.3.14", confidence="high")` → 80 tokens, 1 watch_for pattern surfaced
+
+**Round 4 — cross-source recall competition (v3.3.14):**  
+- `recall("edge functions cold start")` → palace + journal + insight all queried; RRF merged by rank position — no source dominated by raw score inflation
+- Old journal entries (>3 days) correctly faded via Ebbinghaus S=2; palace decisions surfaced regardless of age
+
+**Round 5 — feedback loop (v3.3.14):**  
+- `recall("auth design")` + feedback `{useful: true}` → Beta(2,1) → ×1.33 on next query
+- `recall("auth design")` + feedback `{useful: false}` → Beta(1,2) → ×0.67 penalty
+- Zero-feedback items unchanged (Beta(1,1) → ×1.0 neutral)
+
+172 tests (129 core + 4 smoke + 28 SDK + 11 CLI), 0 failures. Build clean.
 
 ---
 
@@ -585,6 +752,7 @@ Validated over 30+ sessions across 5 production projects:
 | Document | Description |
 |----------|-------------|
 | [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: weekly roll-up, palace-first cold start, promotion verification |
@@ -609,7 +777,11 @@ MIT License.
 
 > **你的智能体记不清楚？听不懂你说话？每次项目都做得非常乱？**
 >
-> **AgentRecall 让它学会理解你的思维方式。** 持久复合记忆 + 智能距离协议。MCP 服务器 + SDK + CLI。
+> **AgentRecall 让它学会理解你的思维方式。**
+>
+> 赋能agent长期记忆，并从错误中学习和纠正，随时间和项目难度进化，越来越擅长和了解用户和agent的思维。
+>
+> 持久复合记忆 + 智能距离协议。MCP 服务器 + SDK + CLI。
 
 ---
 
@@ -617,6 +789,18 @@ MIT License.
   <a href="#arsave-and-arstart"><img src="https://img.shields.io/badge/%2Farsave-保存会话-FF6B6B?style=for-the-badge" alt="/arsave"></a>
   <a href="#arsave-and-arstart"><img src="https://img.shields.io/badge/%2Farstart-加载上下文-4ECDC4?style=for-the-badge" alt="/arstart"></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>
+<p align="center">
+  <a href="#记忆如何复合增长"><img src="https://img.shields.io/badge/1-自动命名-5D34F2?style=for-the-badge" alt="自动命名"></a>
+  <a href="#记忆如何复合增长"><img src="https://img.shields.io/badge/2-索引-0EA5E9?style=for-the-badge" alt="索引"></a>
+  <a href="#记忆如何复合增长"><img src="https://img.shields.io/badge/3-关联性-10B981?style=for-the-badge" alt="关联性"></a>
+  <a href="#记忆如何复合增长"><img src="https://img.shields.io/badge/4-权重与衰减-F59E0B?style=for-the-badge" alt="权重与衰减"></a>
+  <a href="#记忆如何复合增长"><img src="https://img.shields.io/badge/5-反馈回路-EF4444?style=for-the-badge" alt="反馈回路"></a>
+</p>
 
 ## `/arsave` 和 `/arstart`
 
@@ -650,6 +834,14 @@ curl -o ~/.claude/commands/arstart.md https://raw.githubusercontent.com/Goldentr
   → 遗漏一半的任务                        → 自动推送两个仓库
 ```
 
+### 三层价值
+
+**第一层（5 秒）：** 让你的 AI agent 记住上次会话发生了什么。
+
+**第二层（30 秒）：** 每次你纠正 agent——"不，不是那个版本"、"先问我"——这个纠正被永久存储，并在 agent 再犯同样错误之前被召回。10 次会话后，你的 agent 理解你的优先级、你的沟通风格、你的不可妥协项。
+
+**第三层（2 分钟）：** [智能距离协议](https://github.com/Goldentrii/AgentRecall/wiki/Intelligent-Distance)。人类思维和 AI 行动之间的结构性鸿沟无法消除——但可以在每次会话中更好地穿越。纠正就是训练数据。200 行感知上限强制质量优于数量。跨项目洞察意味着学到一次的经验到处适用。
+
 ### 真实会话流程
 
 以下来自一个真实的多日项目，人类给出了分散、非线性的指令。智能体全程使用 AgentRecall：
@@ -660,10 +852,11 @@ curl -o ~/.claude/commands/arstart.md https://raw.githubusercontent.com/Goldentr
 
 /arstart                                     /arstart
   │                                            │
-  ├─ palace_walk ──→ "单仓项目，               ├─ palace_walk ──→ 200 token
-  │                   计划构建 SDK + CLI"       │                  加载周二的架构决策
+  ├─ session_start() ──→ 身份 + 洞察           ├─ session_start() ──→ 加载周二
+  │   活跃房间 + 跨项目匹配                    │   架构决策（约 400 token），
+  │   watch_for 警告                           │   watch_for: "结构化输入"
   │                                            │
-  ├─ recall_insight ──→ 3 条历史教训            ├─ recall_insight
+  ├─ recall("SDK CLI 版本") ──→               ├─ recall("SDK CLI 单仓") ──→
   │   • "结构化分散的输入"                     │   • "不要版本膨胀"
   │   • "先搜索再构建"                         │   • "arsave 放在最显眼的位置"
   │   • "模糊时询问，明确时执行"               │
@@ -672,8 +865,8 @@ curl -o ~/.claude/commands/arstart.md https://raw.githubusercontent.com/Goldentr
 人类："我们需要 SDK、CLI，                     │
   更新 README，修复版本号"                     ▼
   │                                           人类："发布到 npm，
-  ├─ alignment_check                            更新两个 GitHub 仓库"
-  │   confidence: medium                        │
+  ├─ check(goal="SDK+CLI+README",              更新两个 GitHub 仓库"
+  │   confidence="medium")                     │
   │   检测到 4 个任务项                         ├─ 无需重新解释。
   │   → 呈现方案 → 人类确认                    │   智能体已经知道单仓结构、
   │                                             │   包名和版本策略。
@@ -685,10 +878,8 @@ curl -o ~/.claude/commands/arstart.md https://raw.githubusercontent.com/Goldentr
   │
 /arsave
   │
-  ├─ journal_write ──→ 决策 + 任务已保存
-  ├─ awareness_update ──→ "分散输入 →
-  │                        结构化 → 确认 → 执行"
-  └─ palace_write ──→ architecture 房间已更新
+  └─ session_end(summary, insights, trajectory)
+       → 日志 + 感知 + 宫殿 — 一次调用全部完成
 ```
 
 ---
@@ -779,7 +970,7 @@ npx agent-recall-cli palace walk --depth active
 
 一个**学习系统**，弥合人类思维方式与 AI 智能体工作方式之间的差距。不是日志，不是数据库——是一个复合循环，每一次纠正、决策和洞察都让下一次会话比上一次更好。
 
-**问题：** AI 智能体不是真的遗忘——它们是健忘症。记不清楚优先级，分不清主次，教训进入休眠状态，同样的误解重复发生因为没人存储那次纠正。你的意图和智能体行为之间的差距，会话接会话地保持不变。
+**问题：** AI 智能体不是真的遗忘——它们主要是无法抓住人类以为的重点。记不清楚优先级，分不清主次，教训进入休眠状态，同样的误解重复发生因为没人存储那次纠正行为。你的意图、目标和智能体行为之间的差距和割裂导致最终项目效果不佳。
 
 **解决方案：** AgentRecall 将知识存储在五层记忆金字塔中——从快速捕获到跨项目洞察——并通过强制压缩让记忆随时间增值。但更重要的是，它缩小了**智能距离**差距：每一次人类的纠正都被捕获、加权、并在智能体犯同样错误之前被召回。
 
@@ -849,79 +1040,143 @@ ar insight "构建认证中间件"
 
 ### 会话开始 (`/arstart`)
 ```
-1. recall_insight(context="当前任务描述")    → 跨项目相关洞察
-2. palace_walk(depth="active")               → 项目上下文 + 感知摘要
+session_start()  → 身份、洞察、活跃房间、跨项目匹配、最近活动、watch_for 预警 — 一次调用
 ```
 
 ### 工作中
 ```
-3. alignment_check(goal="...", confidence="medium")   → 大任务前确认理解
-4. palace_write(room="architecture", content="...")   → 永久知识 + 交叉引用
-5. journal_capture(question="...", answer="...")       → 轻量问答记录
+remember("我们决定用 GraphQL 替代 REST")    → 自动分类并路由到正确的存储
+recall("认证设计")                           → 搜索所有存储，排名结果
+check(goal="构建认证", confidence="medium")  → 验证理解，获取预警
 ```
 
-### 会话结束
+### 会话结束 (`/arsave`)
 ```
-6. journal_write(content="...", section="decisions")  → 每日日志
-7. awareness_update(insights=[...])                    → 洞察复合到感知系统
-8. context_synthesize(consolidate=true)                → 日志内容提升到宫殿
+session_end(summary="...", insights=[...], trajectory="...")  → 日志 + 感知 + 整合
 ```
 
 ---
 
-## 22 个 MCP 工具
+## 5 个 MCP 工具
 
-### 记忆宫殿（5 个）
+AgentRecall 目前只向 agent 提供 5 个工具。每个工具内部组合多个子系统 — agent 不需要了解内部管道。
 
 | 工具 | 功能 |
 |------|------|
-| `palace_read` | 读取房间内容或列出所有房间 |
-| `palace_write` | 写入记忆，自动通过 `[[wikilinks]]` 扇出交叉引用 |
-| `palace_walk` | 渐进式冷启动：identity (~50 tok) → active (~200) → relevant (~500) → full (~2000) |
-| `palace_lint` | 健康检查：过期、孤立、低显著性房间。`fix=true` 自动归档 |
-| `palace_search` | 全房间搜索，按显著性评分排序 |
+| `session_start` | 加载项目上下文。返回身份、洞察、活跃房间、跨项目匹配、最近活动、以及来自历史纠正的 `watch_for` 预警。一次调用，约 400 token。 |
+| `remember` | 保存记忆。自动分类内容（bug 修复、架构决策、洞察、会话笔记）并路由到正确的存储。自动生成语义化名称便于未来检索。 |
+| `recall` | 通过**互惠排名融合（RRF）**一次搜索所有记忆 — 每个来源内部独立排名，再按位置合并，避免任何单一来源靠原始分数主导结果。返回带稳定 ID 的排名结果。支持 `feedback` 评价：正面提升排名，负面降低。查询感知 — 某次搜索的反馈不影响无关查询。 |
+| `session_end` | 一次调用保存全部。写入日志、更新感知、整合到宫殿、归档被替换的洞察（不删除 — 支持复活）。 |
+| `check` | 记录你对人类意图的理解。返回历史纠正模式的 `watch_for` 预警。支持记录 `human_correction` 和 `delta`。3+ 次的强模式自动提升为感知洞察。 |
 
-### 感知与洞察（2 个）
+### 旧版工具
 
-| 工具 | 功能 |
-|------|------|
-| `awareness_update` | 添加洞察到复合感知系统。自动合并相似洞察，检测跨洞察模式 |
-| `recall_insight` | 开始任务前，召回跨项目的相关洞察 |
+原始 22 个子系统工具（palace_write、journal_capture、awareness_update 等）通过 SDK 和 CLI 仍然可用，适用于向后兼容和高级用例。MCP 服务器默认不注册这些工具。
+
+---
 
-### 会话记忆（6 个）
+## 记忆如何复合增长
 
-| 工具 | 功能 |
-|------|------|
-| `journal_read` | 按日期读取日志，支持章节过滤 |
-| `journal_write` | 写入每日日志。可选 `palace_room` 同步到宫殿 |
-| `journal_capture` | 轻量问答捕获 |
-| `journal_list` | 列出最近日志 |
-| `journal_search` | 全文搜索。`include_palace=true` 同时搜索宫殿 |
-| `journal_projects` | 列出所有项目 |
+<p align="center">
+  <a href="#1-自动命名"><img src="https://img.shields.io/badge/1-自动命名-5D34F2?style=for-the-badge" alt="自动命名"></a>
+  <a href="#2-索引"><img src="https://img.shields.io/badge/2-索引-0EA5E9?style=for-the-badge" alt="索引"></a>
+  <a href="#3-关联性"><img src="https://img.shields.io/badge/3-关联性-10B981?style=for-the-badge" alt="关联性"></a>
+  <a href="#4-权重与衰减"><img src="https://img.shields.io/badge/4-权重与衰减-F59E0B?style=for-the-badge" alt="权重与衰减"></a>
+  <a href="#5-反馈回路"><img src="https://img.shields.io/badge/5-反馈回路-EF4444?style=for-the-badge" alt="反馈回路"></a>
+</p>
 
-### 架构工具（4 个）
+> 记忆不是清单，而是一个 1+1+1 > 3 的复合系统。每个子系统喂养下一个 — 命名使检索成为可能，检索使反馈成为可能，反馈使排名成为可能，排名让正确的记忆在正确的时间浮现。10 个会话后，系统知道的比任何单条记忆都多。
 
-| 工具 | 功能 |
-|------|------|
-| `journal_state` | JSON 状态层 — agent 间毫秒级结构化交接 |
-| `journal_cold_start` | 宫殿优先冷启动：先加载身份+感知+高权重房间(~200 token)，再加载日志 |
-| `journal_archive` | 归档旧条目到冷存储 |
-| `journal_rollup` | 将旧日志压缩为周报。防止日志无限积累。`dry_run=true` 预览 |
+### 1. 自动命名
 
-### 知识工具（2 个）
+Agent 在保存的瞬间对内容理解最深。AgentRecall 把这种理解捕获为语义化的名称 — 不是 `"mcp-verified"` 而是 `"verified-agentrecall-mcp-22tools-functional"`。
 
-| 工具 | 功能 |
-|------|------|
-| `knowledge_write` | 写入永久教训 — 动态类别，自动创建宫殿房间 |
-| `knowledge_read` | 按项目、类别或搜索词读取教训 |
+```
+内容: "修复了支付处理器在退款时崩溃的严重 bug"
+  → 类型检测: bug-fix
+  → 关键词提取: payment, processor, crashed, refunds
+  → 生成名称: bug-fix-payment-processor-crashed
+```
 
-### 对齐工具（3 个）
+好的命名本身就是检索的第一层。一个命名良好的记忆，不需要搜索算法就能被找到 80%。
 
-| 工具 | 功能 |
-|------|------|
-| `alignment_check` | 记录置信度 + 假设 → 人类在工作前纠正 |
-| `nudge` | 检测与过去决策的矛盾 → 在造成损失前提出 |
-| `context_synthesize` | L3 合成。`consolidate=true` 将结果写入宫殿房间 |
+### 2. 索引
+
+每条记忆在三个索引系统中都有地址：
+
+| 索引 | 追踪什么 | Token 开销 |
+|------|---------|-----------|
+| **宫殿索引** | 房间目录 + 显著性评分 | 扫描约 50 token |
+| **洞察索引** | 跨项目教训 + 关键词匹配 | 查询约 30 token |
+| **感知文档** | 200 行复合文档（强制合并） | 约 200 token，但每一行都承载交叉验证的权重 |
+
+索引是轻量指针。Agent 先扫描索引，只在需要时才加载完整内容。
+
+### 3. 关联性
+
+相关的记忆会自动连接 — 无需手写 wikilinks。
+
+```
+Agent 写入: "JWT 刷新令牌轮换防止会话固定攻击"
+  → 关键词: jwt, refresh, rotation, session
+  → "architecture" 房间标签: ["technical"]
+  → "knowledge" 房间有 "session management" 教训
+  → 自动创建边: architecture ←→ knowledge (权重 0.3)
+```
+
+当你 `recall("会话安全")` 时，系统不只是关键词匹配 — 它沿着边跳 1 步，从关联房间中浮现相关记忆。关联性把孤立的记忆变成知识图谱。
+
+### 4. 权重与衰减
+
+不是所有记忆都平等。显著性评分确保最重要的记忆先浮现：
+
+```
+显著性 = 时效性(0.30) + 访问频率(0.25) + 连接数(0.20) + 紧迫性(0.15) + 重要性(0.10)
+```
+
+- 架构决策以 0.98/天 衰减（持久）。阻塞项以 0.90/天 衰减（短暂）。
+- 你实际访问的记忆越来越强。从不回顾的记忆逐渐淡化。
+- 被替换的洞察不会消亡 — 它们进入归档。如果未来的洞察匹配，它们会复活。
+
+`recall` 基于**艾宾浩斯遗忘曲线**（1885）`R(t) = e^(−t/S)` 对不同记忆类型设定不同衰减强度：
+
+| 记忆类型 | S（天） | 1天后保留率 | 1周后保留率 |
+|----------|---------|------------|------------|
+| 日志（情景记忆） | 2 | 60% | ~7% |
+| 知识 / Bug 修复（程序记忆） | 180 | 99% | 96% |
+| 宫殿 / 架构决策（语义记忆） | 9999 | ≈100% | ≈100% |
+
+旧日志的噪音在数天内消退，架构决策永久保留。相同查询，始终得到正确结果。
+
+### 5. 反馈回路
+
+系统通过**贝叶斯 Beta 分布**学习什么有用、什么没用——这是从二元观察中估计"真实有用性"的数学最优解（`E[Beta(α,β)] = (pos+1)/(pos+neg+2)`）：
+
+```
+会话 1: recall("认证设计") → 返回 5 条结果
+  Agent 评价: 结果 #1 有用, 结果 #3 没用
+  → 存入 feedback-log.json（带查询上下文）
+
+会话 2: recall("认证模式") → 类似查询
+  → 结果 #1: Beta(2,1) → E[U]=0.67 → ×1.33 分数倍增
+  → 结果 #3: Beta(1,2) → E[U]=0.33 → ×0.67 分数惩罚
+  → 排名变化: 有用的记忆上升，噪音下沉
+```
+
+无反馈的条目保持中性（×1.0）。反馈是查询感知的 — 把一条结果标记为"对认证设计没用"不会惩罚它在"数据库设计"中的表现。系统按上下文学习，而非全局惩罚。
+
+### 复合效应
+
+```
+会话 1:    保存 3 条记忆（自动命名、索引、创建边）
+会话 5:    recall 浮现会话 1-4 的记忆，反馈优化排名
+会话 10:   watch_for 在错误重复之前警告 agent
+会话 20:   感知包含 10 条交叉验证的洞察（从 40+ 条原始观察合并）
+会话 50:   Agent 了解你的优先级、盲点和沟通风格
+           — 不是因为被告知，而是因为每次纠正都在复合增长
+```
+
+每一层放大其他层。自动命名让索引有意义。索引让关联性成为可能。关联性让检索精准。精准检索产生有意义的反馈。反馈让下一次检索更好。循环复合增长。
 
 ---
 
@@ -1026,6 +1281,7 @@ L5: 洞察索引     recall_insight            「跨项目的经验」
 | 文档 | 说明 |
 |------|------|
 | [智能距离协议](docs/intelligent-distance-protocol.md) | 基础理论 — 人类与 AI 之间的差距是结构性的，如何减少两个物种之间的沟通信息损失 |
+| [评分设计原理](docs/SCORING.md) | 评分系统的工作原理 — RRF、艾宾浩斯、Beta 分布及其修复的 bug |
 | [MCP 适配器规范](docs/mcp-adapter-spec.md) | 基于 AgentRecall 构建适配器的技术规范 |
 | [SDK 设计](docs/sdk-design.md) | SDK 架构设计文档 |
 | [v3.4 升级说明](UPGRADE-v3.4.md) | 周报压缩、宫殿优先冷启动、提升验证 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-recall-mcp",
-  "version": "3.3.14",
+  "version": "3.3.15",
   "description": "Memory Palace MCP server for AI agents",
   "type": "module",
   "main": "dist/index.js",