agent-recall-mcp 3.3.3 → 3.3.5

package/README.md

@@ -1,65 +1,99 @@
-<p align="center">
-  <h1 align="center">AgentRecall</h1>
-  <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>
+<h1 align="center">AgentRecall</h1>
+
+<p align="center"><strong>Persistent, compounding memory for AI agents. MCP server + SDK + CLI.</strong></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://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-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/MCP-22_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">
 </p>
 
+<p align="center">
+  <b>EN:</b>&nbsp;
+  <a href="#why-choose-agentrecall">Why</a> ·
+  <a href="#three-ways-to-use-it">Use</a> ·
+  <a href="#what-is-agentrecall">What</a> ·
+  <a href="#quick-start">Install</a> ·
+  <a href="#22-mcp-tools">Tools</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="#sdk-api-1">SDK</a> ·
+  <a href="#cli-命令">CLI</a> ·
+  <a href="#架构">架构</a>
+</p>
+
 ---
 
-## `/arsave` — Save Everything in One Shot
+## Why Choose AgentRecall
 
-> **Two commands. That's all you need.**
+**Your agents forget everything between sessions.** Decisions evaporate. Mistakes repeat. Context rebuilds from scratch every time. AgentRecall fixes this with persistent memory that compounds — getting smarter, not bigger.
 
-| Command | When | What it does |
-|---------|------|-------------|
-| **`/arsave`** | End of session | Write journal + consolidate to palace + update awareness + optional git push |
-| **`/arstart`** | Start of session | Recall cross-project insights + walk palace + load context |
+- **Near-universal compatibility.** MCP server for any MCP-compatible agent (Claude Code, Cursor, Windsurf, VS Code, Codex). SDK for any JS/TS framework (LangChain, CrewAI, Vercel AI SDK, custom agents). CLI for terminal and CI workflows. One memory system, every surface.
+
+- **Compounding awareness, not infinite logs.** Memory is capped at 200 lines. New insights either merge with existing ones (strengthening them) or replace the weakest. After 100 sessions, your awareness file is still 200 lines — but each line carries the weight of cross-validated, confirmed observations.
 
-Type `/arsave` after a long project session. Everything gets saved. Type `/arstart` next time. Everything loads back.
+- **Cross-project recall.** Lessons learned in one project apply everywhere. Built a rate limiter last month? That lesson surfaces when you're building one today — in a different repo, through a different agent.
 
+- **Zero cloud, zero telemetry, all local.** Everything is markdown on disk. Browse it in Obsidian, grep it in the terminal, version it in git. No accounts, no API keys, no lock-in.
+
+---
+
+## Three Ways to Use It
+
+**MCP** — for AI agents (Claude Code, Cursor, Windsurf, VS Code, Codex):
 ```bash
-# Install commands (one-time)
-mkdir -p ~/.claude/commands
-curl -o ~/.claude/commands/arsave.md https://raw.githubusercontent.com/Goldentrii/AgentRecall/main/commands/arsave.md
-curl -o ~/.claude/commands/arstart.md https://raw.githubusercontent.com/Goldentrii/AgentRecall/main/commands/arstart.md
+claude mcp add agent-recall -- npx -y agent-recall-mcp
+```
+
+**SDK** — for any JS/TS application (LangChain, CrewAI, Vercel AI SDK, custom):
+```typescript
+import { AgentRecall } from "agent-recall-sdk";
+const memory = new AgentRecall({ project: "my-app" });
+await memory.capture("What stack?", "Next.js + Postgres");
+```
+
+**CLI** — for terminal workflows and CI:
+```bash
+npx agent-recall-cli capture "What stack?" "Next.js + Postgres"
+npx agent-recall-cli palace walk --depth active
 ```
 
 ---
 
 ## What Is AgentRecall?
 
-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.
+A **persistent memory system** that gives AI agents **compounding awareness** across sessions. Not a log. Not a database. A second brain that gets smarter the more you use it.
 
-**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
+**The problem:** AI agents start from zero every session. They forget your decisions, repeat your mistakes, lose context mid-project, and misunderstand you the same way twice.
 
-```
-┌──────────────────────────────────────────────────────────────┐
-│  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)   │
-└──────────────────────────────────────────────────────────────┘
-```
+**The fix:** AgentRecall stores knowledge in a five-layer memory pyramid — from quick captures to cross-project insights — and forces compression so memory gets more valuable over time, not more bloated.
+
+| Without AgentRecall | With AgentRecall |
+|---------------------|------------------|
+| Agent forgets yesterday's decisions | Decisions live in palace rooms, loaded on cold start |
+| Same mistake repeated across sessions | `recall_insight` surfaces past lessons before work starts |
+| 5 min context recovery on each session start | 2 second cold start from palace (~200 tokens) |
+| Flat memory files that grow forever | 200-line awareness cap forces merge-or-replace |
+| Knowledge trapped in one project | Cross-project insights match by keyword |
+| Agent misunderstands, you correct, it forgets | `alignment_check` records corrections permanently |
 
 ---
 
 ## Quick Start
 
+### MCP Server (for AI agents)
+
 ```bash
 # Claude Code
 claude mcp add agent-recall -- npx -y agent-recall-mcp
@@ -73,7 +107,7 @@ claude mcp add agent-recall -- npx -y agent-recall-mcp
 # Windsurf — ~/.codeium/windsurf/mcp_config.json
 { "mcpServers": { "agent-recall": { "command": "npx", "args": ["-y", "agent-recall-mcp"] } } }
 
-# Codex — ~/.codex/config.toml (or .codex/config.toml for project-scoped)
+# Codex
 codex mcp add agent-recall -- npx -y agent-recall-mcp
 ```
 
@@ -84,6 +118,81 @@ curl -o ~/.claude/skills/agent-recall/SKILL.md \
   https://raw.githubusercontent.com/Goldentrii/AgentRecall/main/SKILL.md
 ```
 
+### SDK (for JS/TS applications)
+
+```bash
+npm install agent-recall-sdk
+```
+
+```typescript
+import { AgentRecall } from "agent-recall-sdk";
+
+const memory = new AgentRecall({ project: "my-app" });
+
+// Capture knowledge
+await memory.capture("What ORM?", "Drizzle — type-safe, lightweight");
+
+// Write to memory palace
+await memory.palaceWrite("architecture", "Stack: Next.js 16 + Drizzle + Postgres");
+
+// Cold start — load project context in ~200 tokens
+const context = await memory.coldStart();
+
+// Recall cross-project insights
+const insights = await memory.recallInsight("rate limiting");
+
+// Walk the palace at different depths
+const walk = await memory.walk("active");
+```
+
+### CLI (for terminal and CI)
+
+```bash
+npm install -g agent-recall-cli
+# or use npx: npx agent-recall-cli <command>
+```
+
+```bash
+# Capture a Q&A pair
+ar capture "What ORM?" "Drizzle" --project my-app
+
+# Read today's journal
+ar read --date latest
+
+# Walk the memory palace
+ar palace walk --depth active
+
+# Search across all memory
+ar search "rate limiting" --include-palace
+
+# Recall cross-project insights
+ar insight "building auth middleware"
+
+# Write to a palace room
+ar palace write architecture "Switched from REST to tRPC"
+
+# Compact old journals into weekly summaries
+ar rollup --min-age-days 14
+```
+
+---
+
+## `/arsave` and `/arstart`
+
+> **Two commands. That's all you need for session management.**
+
+| Command | When | What it does |
+|---------|------|-------------|
+| **`/arsave`** | End of session | Write journal + consolidate to palace + update awareness + optional git push |
+| **`/arstart`** | Start of session | Recall cross-project insights + walk palace + load context |
+
+```bash
+# Install commands (one-time, Claude Code only)
+mkdir -p ~/.claude/commands
+curl -o ~/.claude/commands/arsave.md https://raw.githubusercontent.com/Goldentrii/AgentRecall/main/commands/arsave.md
+curl -o ~/.claude/commands/arstart.md https://raw.githubusercontent.com/Goldentrii/AgentRecall/main/commands/arstart.md
+```
+
 ---
 
 ## How an Agent Uses AgentRecall
@@ -110,7 +219,7 @@ curl -o ~/.claude/skills/agent-recall/SKILL.md \
 
 ---
 
-## 21 MCP Tools
+## 22 MCP Tools
 
 ### Memory Palace (5 tools)
 
@@ -140,13 +249,14 @@ curl -o ~/.claude/skills/agent-recall/SKILL.md \
 | `journal_search` | Full-text search across history. `include_palace=true` for palace too |
 | `journal_projects` | List all tracked projects |
 
-### Architecture (3 tools)
+### Architecture (4 tools)
 
 | Tool | Purpose |
 |------|---------|
 | `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_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 |
 
 ### Knowledge (2 tools)
 
@@ -165,88 +275,190 @@ curl -o ~/.claude/skills/agent-recall/SKILL.md \
 
 ---
 
-## Architecture
+## SDK API
 
-### Memory Palace
+The `agent-recall-sdk` package exposes the `AgentRecall` class — a programmatic interface to the full memory system. Use it to add persistent, compounding memory to any JS/TS agent framework: LangChain, CrewAI, Vercel AI SDK, AutoGen, or your own.
 
-Inspired by the Method of Loci, Karpathy's LLM Wiki, and nashsu/llm_wiki.
+```typescript
+import { AgentRecall } from "agent-recall-sdk";
 
-```
-~/.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
+const ar = new AgentRecall({ project: "my-project" });
 ```
 
-### Key Mechanisms
+### Core Methods
 
-**Fan-out writes** — Write to one room, cross-references auto-update in related rooms via `[[wikilinks]]`. Mechanical, zero LLM cost.
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `capture(question, answer, opts?)` | `JournalCaptureResult` | Quick Q&A capture (L1 memory) |
+| `journalWrite(content, opts?)` | `JournalWriteResult` | Write daily journal entry |
+| `journalRead(opts?)` | `JournalReadResult` | Read journal by date or "latest" |
+| `journalSearch(query, opts?)` | `JournalSearchResult` | Full-text search across journals |
+| `coldStart()` | `JournalColdStartResult` | Palace-first context loading (~200 tokens) |
 
-**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.
+### Palace Methods
 
-**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.
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `palaceWrite(room, content, opts?)` | `PalaceWriteResult` | Write to a room with fan-out cross-refs |
+| `palaceRead(room?, topic?)` | `PalaceReadResult` | Read room content or list all rooms |
+| `walk(depth?, focus?)` | `PalaceWalkResult` | Progressive walk: identity → active → relevant → full |
+| `palaceSearch(query, room?)` | `PalaceSearchResult` | Search rooms by content |
+| `lint(fix?)` | `PalaceLintResult` | Health check and auto-archive |
 
-**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.
+### Awareness & Insight Methods
 
-**Obsidian-compatible** — Every palace file has YAML frontmatter + `[[wikilinks]]`. Open `palace/` as an Obsidian vault → graph view shows room connections. Zero Obsidian dependency.
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `awarenessUpdate(insights, opts?)` | `AwarenessUpdateResult` | Compound new insights into awareness |
+| `readAwareness()` | `string` | Read the 200-line awareness document |
+| `recallInsight(context, opts?)` | `RecallInsightResult` | Cross-project insight recall |
+
+### Alignment Methods
 
-### Intelligent Distance Protocol
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `alignmentCheck(input)` | `AlignmentCheckResult` | Record confidence + assumptions |
+| `nudge(input)` | `NudgeResult` | Detect contradictions with past decisions |
+| `synthesize(opts?)` | `ContextSynthesizeResult` | L3 synthesis, optional palace consolidation |
 
-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:
+### LangChain / CrewAI Integration Example
 
-| 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") |
+```typescript
+import { AgentRecall } from "agent-recall-sdk";
+
+const memory = new AgentRecall({ project: "langchain-app" });
+
+// Before agent runs — load context
+const context = await memory.coldStart();
+const insights = await memory.recallInsight("current task description");
+
+// Inject into system prompt
+const systemPrompt = `You have persistent memory:\n${context.summary}\n\nRelevant insights:\n${insights.matches.map(m => m.insight).join("\n")}`;
+
+// After agent runs — save what was learned
+await memory.capture("What did the agent decide?", agentOutput);
+await memory.awarenessUpdate([{
+  insight: "Rate limiting needs token bucket, not fixed window",
+  evidence: "Fixed window caused burst failures in load test",
+  applies_when: ["rate-limiting", "api-design", "load-testing"]
+}]);
+```
 
 ---
 
-## Supported Agents
+## CLI Commands
 
-| Agent | MCP | Skill | Notes |
-|-------|:---:|:-----:|-------|
-| Claude Code | ✅ | ✅ | Full support — MCP + SKILL.md |
-| OpenAI Codex | ✅ | — | `codex mcp add` — config.toml |
-| 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 |
+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
+
+JOURNAL:
+  ar read [--date YYYY-MM-DD] [--section <name>]
+  ar write <content> [--section <name>]
+  ar capture <question> <answer> [--tags tag1,tag2]
+  ar list [--limit N]
+  ar search <query> [--include-palace]
+  ar state read|write [data]
+  ar cold-start
+  ar archive [--older-than-days N]
+  ar rollup [--min-age-days N] [--dry-run]
+
+PALACE:
+  ar palace read [<room>] [--topic <name>]
+  ar palace write <room> <content> [--importance high|medium|low]
+  ar palace walk [--depth identity|active|relevant|full]
+  ar palace search <query>
+  ar palace lint [--fix]
+
+AWARENESS:
+  ar awareness read
+  ar awareness update --insight "title" --evidence "ev" --applies-when kw1,kw2
+
+INSIGHT:
+  ar insight <context> [--limit N]
+
+META:
+  ar projects
+  ar synthesize [--entries N]
+  ar knowledge write --category <cat> --title "t" --what "w" --cause "c" --fix "f"
+  ar knowledge read [--category <cat>]
+
+GLOBAL FLAGS:
+  --root <path>     Storage root (default: ~/.agent-recall)
+  --project <slug>  Project override
+```
 
 ---
 
-## Design Philosophy
+## Architecture
+
+### Five-Layer Memory Pyramid
+
+```
+L1: Working Memory     journal_capture           "what happened"
+L2: Episodic Memory    journal_write             "what it means"
+L3: Memory Palace      palace_write / walk       "knowledge across sessions"
+L4: Awareness          awareness_update          "compounding insights"
+L5: Insight Index      recall_insight            "cross-project experience"
+```
+
+### Key Mechanisms
+
+**Fan-out writes** — Write to one room, cross-references auto-update in related rooms via `[[wikilinks]]`. Mechanical, zero LLM cost.
+
+**Salience scoring** — Every room has a salience score: `importance(0.4) + recency(0.3) + access_frequency(0.2) + connections(0.1)`. High-salience rooms surface first. Below threshold → auto-archive.
 
-**Memory is not the goal. Understanding is.**
+**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.
 
-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.
+**Cross-project insight recall** — `insights-index.json` maps insights to situations via keywords. `recall_insight("building quality gates")` returns relevant lessons from any project, ranked by severity x confirmation count.
 
-**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.
+**Obsidian-compatible** — Every palace file has YAML frontmatter + `[[wikilinks]]`. Open `palace/` as an Obsidian vault → graph view shows room connections. Zero Obsidian dependency.
 
-**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.
+### Storage Layout
 
-**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.
+```
+~/.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/
+        YYYY-MM-DD.md             # Daily journal
+        YYYY-MM-DD-log.md         # L1 captures
+        YYYY-MM-DD.state.json     # JSON state
+      palace/
+        identity.md               # ~50 token project identity card
+        palace-index.json          # Room catalog + salience scores
+        graph.json                 # Cross-reference edges
+        rooms/
+          goals/                   # Active goals, evolution
+          architecture/            # Technical decisions, patterns
+          blockers/                # Current and resolved
+          alignment/               # Human corrections
+          knowledge/               # Learned lessons by category
+          <custom>/                # Agents create rooms on demand
+```
+
+---
+
+## Platform Compatibility
+
+| Platform | MCP | SDK | CLI | Notes |
+|----------|:---:|:---:|:---:|-------|
+| Claude Code | ✅ | ✅ | ✅ | Full support — MCP + SKILL.md + commands |
+| Cursor | ✅ | ✅ | ✅ | MCP via .cursor/mcp.json |
+| VS Code (Copilot) | ✅ | ✅ | ✅ | MCP via .vscode/mcp.json |
+| Windsurf | ✅ | ✅ | ✅ | MCP via mcp_config.json |
+| OpenAI Codex | ✅ | ✅ | ✅ | `codex mcp add` — config.toml |
+| Claude Desktop | ✅ | — | — | MCP server |
+| LangChain / LangGraph | — | ✅ | — | `new AgentRecall()` in your chain |
+| CrewAI | — | ✅ | — | SDK in tool definitions |
+| Vercel AI SDK | — | ✅ | — | SDK in server actions |
+| Custom JS/TS agents | — | ✅ | ✅ | SDK + CLI for any agent framework |
+| CI / GitHub Actions | — | — | ✅ | `npx agent-recall-cli` in workflows |
+| Any MCP agent | ✅ | — | — | Standard MCP protocol |
 
 ---
 
@@ -261,13 +473,24 @@ Validated over 30+ sessions across 5 production projects:
 
 ---
 
+## Docs
+
+| 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 |
+| [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 |
+
+---
+
 ## Contributing
 
-Built by [tongwu](https://github.com/Goldentrii).
+Built by [tongwu](https://github.com/Goldentrii) at [Novada](https://www.novada.com).
 
 - Issues & feedback: [GitHub Issues](https://github.com/Goldentrii/AgentRecall/issues)
-- Email: tongwu0824@gmail.com
-- Protocol spec: [docs/intelligent-distance-protocol.md](https://github.com/Goldentrii/AgentRecall/blob/main/docs/intelligent-distance-protocol.md)
+- Email: [tong.wu@novada.com](mailto:tong.wu@novada.com)
+- Website: [novada.com](https://www.novada.com)
 
 MIT License.
 
@@ -277,25 +500,68 @@ MIT License.
 
 # AgentRecall（中文文档）
 
-> 给你的 AI 智能体一个会成长的第二大脑。
+> **你的 AI 智能体每次对话都从零开始。AgentRecall 解决这个问题。**
+
+---
+
+## 为什么选择 AgentRecall
+
+**你的智能体在会话之间遗忘一切。** 决策蒸发，错误重复，上下文每次从零构建。AgentRecall 用持久记忆修复这个问题 — 记忆会复合增长，而不是无限膨胀。
+
+- **近乎通用的兼容性。** MCP 服务器支持所有 MCP 兼容智能体（Claude Code、Cursor、Windsurf、VS Code、Codex）。SDK 支持任何 JS/TS 框架（LangChain、CrewAI、Vercel AI SDK、自定义智能体）。CLI 支持终端和 CI 工作流。一套记忆系统，覆盖所有场景。
+
+- **复合感知，而非无限日志。** 记忆上限 200 行。新洞察要么与已有的合并（增强），要么替换最弱的。100 个会话后，感知文件仍然是 200 行 — 但每一行都承载着经过交叉验证的确认观察。
+
+- **跨项目召回。** 在一个项目中学到的教训适用于所有项目。上个月做了限流器？今天在另一个项目构建时，那个教训会自动浮现。
+
+- **零云端，零遥测，全部本地。** 一切都是磁盘上的 markdown。在 Obsidian 中浏览，在终端中 grep，在 git 中版本管理。无需账户、API 密钥或锁定。
+
+---
+
+## 三种使用方式
+
+**MCP** — 面向 AI 智能体（Claude Code、Cursor、Windsurf、VS Code、Codex）：
+```bash
+claude mcp add agent-recall -- npx -y agent-recall-mcp
+```
+
+**SDK** — 面向任何 JS/TS 应用（LangChain、CrewAI、Vercel AI SDK、自定义）：
+```typescript
+import { AgentRecall } from "agent-recall-sdk";
+const memory = new AgentRecall({ project: "my-app" });
+await memory.capture("用什么技术栈？", "Next.js + Postgres");
+```
+
+**CLI** — 面向终端工作流和 CI：
+```bash
+npx agent-recall-cli capture "用什么技术栈？" "Next.js + Postgres"
+npx agent-recall-cli palace walk --depth active
+```
 
 ---
 
 ## AgentRecall 是什么？
 
-AgentRecall 是一个 **MCP 服务器**（Model Context Protocol），为 AI 智能体提供持久化记忆、跨项目洞察召回和自复合感知系统。支持 Claude Code、Cursor、VS Code、Windsurf 及所有 MCP 兼容的智能体。
+一个**持久记忆系统**，让 AI 智能体拥有**跨会话复合感知**。不是日志，不是数据库——是一个用得越多越聪明的第二大脑。
 
-**不只是记忆系统。** 大多数智能体记忆工具只做存储和检索。AgentRecall 还能：
-- **组织** — 知识按主题房间分类（记忆宫殿）
-- **复合** — 洞察随时间合并增强，不是单纯累积
-- **交叉引用** — 写入一个房间时自动更新相关房间
-- **召回** — 开始任务前，自动呈现任何项目中的相关经验教训
-- **检测误解** — 测量人类意图和智能体理解之间的差距
+**问题：** AI 智能体每次会话都是全新开始。忘记你的决策，重复同样的错误，丢失项目上下文，以同样的方式误解你。
+
+**解决方案：** AgentRecall 将知识存储在五层记忆金字塔中——从快速捕获到跨项目洞察——并通过强制压缩让记忆随时间增值，而不是膨胀。
+
+| 没有 AgentRecall | 有 AgentRecall |
+|-----------------|---------------|
+| 智能体忘记昨天的决策 | 决策存在宫殿房间，冷启动时加载 |
+| 跨会话重复同样的错误 | `recall_insight` 工作前自动呈现过去教训 |
+| 每次开始需要 5 分钟恢复上下文 | 2 秒冷启动，从宫殿加载（~200 token） |
+| 平面记忆文件无限增长 | 200 行感知上限，强制合并或替换 |
+| 知识锁在单个项目 | 跨项目洞察按关键词匹配 |
 
 ---
 
 ## 快速开始
 
+### MCP 服务器（面向 AI 智能体）
+
 ```bash
 # Claude Code
 claude mcp add agent-recall -- npx -y agent-recall-mcp
@@ -317,6 +583,31 @@ curl -o ~/.claude/skills/agent-recall/SKILL.md \
   https://raw.githubusercontent.com/Goldentrii/AgentRecall/main/SKILL.md
 ```
 
+### SDK（面向 JS/TS 应用）
+
+```bash
+npm install agent-recall-sdk
+```
+
+```typescript
+import { AgentRecall } from "agent-recall-sdk";
+
+const memory = new AgentRecall({ project: "my-app" });
+await memory.capture("用什么 ORM？", "Drizzle — 类型安全、轻量");
+await memory.palaceWrite("architecture", "技术栈：Next.js 16 + Drizzle + Postgres");
+const context = await memory.coldStart();
+```
+
+### CLI（面向终端和 CI）
+
+```bash
+npm install -g agent-recall-cli
+
+ar capture "用什么 ORM？" "Drizzle" --project my-app
+ar palace walk --depth active
+ar insight "构建认证中间件"
+```
+
 ---
 
 ## 智能体使用流程
@@ -343,7 +634,7 @@ curl -o ~/.claude/skills/agent-recall/SKILL.md \
 
 ---
 
-## 21 个 MCP 工具
+## 22 个 MCP 工具
 
 ### 记忆宫殿（5 个）
 
@@ -373,13 +664,14 @@ curl -o ~/.claude/skills/agent-recall/SKILL.md \
 | `journal_search` | 全文搜索。`include_palace=true` 同时搜索宫殿 |
 | `journal_projects` | 列出所有项目 |
 
-### 架构工具（3 个）
+### 架构工具（4 个）
 
 | 工具 | 功能 |
 |------|------|
 | `journal_state` | JSON 状态层 — agent 间毫秒级结构化交接 |
-| `journal_cold_start` | 缓存感知冷启动：热 (0-1天) / 温 (2-7天) / 冷 (7天+) |
+| `journal_cold_start` | 宫殿优先冷启动：先加载身份+感知+高权重房间(~200 token)，再加载日志 |
 | `journal_archive` | 归档旧条目到冷存储 |
+| `journal_rollup` | 将旧日志压缩为周报。防止日志无限积累。`dry_run=true` 预览 |
 
 ### 知识工具（2 个）
 
@@ -398,65 +690,119 @@ curl -o ~/.claude/skills/agent-recall/SKILL.md \
 
 ---
 
-## 架构
+## SDK API
 
-### 五层记忆模型
+`agent-recall-sdk` 提供 `AgentRecall` 类 — 完整记忆系统的编程接口。可用于 LangChain、CrewAI、Vercel AI SDK 或任何自定义 JS/TS 智能体框架。
 
+```typescript
+import { AgentRecall } from "agent-recall-sdk";
+const ar = new AgentRecall({ project: "my-project" });
 ```
-┌──────────────────────────────────────────────────────────────┐
-│  L1: 工作记忆     journal_capture          「发生了什么」     │
-│  L2: 情景记忆     journal_write            「这意味着什么」   │
-│  L3: 记忆宫殿     palace_write / walk      「跨会话的知识」   │
-│  L4: 感知系统     awareness_update          「复合的洞察」     │
-│  L5: 洞察索引     recall_insight            「跨项目的经验」   │
-└──────────────────────────────────────────────────────────────┘
+
+| 方法 | 说明 |
+|------|------|
+| `capture(question, answer, opts?)` | 快速问答捕获（L1 记忆） |
+| `journalWrite(content, opts?)` | 写入每日日志 |
+| `coldStart()` | 宫殿优先上下文加载（~200 token） |
+| `palaceWrite(room, content, opts?)` | 写入房间，自动扇出交叉引用 |
+| `palaceRead(room?, topic?)` | 读取房间内容 |
+| `walk(depth?, focus?)` | 渐进式宫殿漫步 |
+| `awarenessUpdate(insights, opts?)` | 复合新洞察到感知系统 |
+| `recallInsight(context, opts?)` | 跨项目洞察召回 |
+| `alignmentCheck(input)` | 记录置信度和假设 |
+| `synthesize(opts?)` | L3 合成，可选宫殿整合 |
+
+---
+
+## CLI 命令
+
+`agent-recall-cli` 提供 `ar` 命令，用于终端工作流和 CI 管道。
+
+```bash
+# 日志
+ar read [--date YYYY-MM-DD] [--section <name>]
+ar write <content> [--section <name>]
+ar capture <question> <answer> [--tags tag1,tag2]
+ar search <query> [--include-palace]
+ar rollup [--min-age-days N] [--dry-run]
+
+# 宫殿
+ar palace read [<room>]
+ar palace write <room> <content> [--importance high|medium|low]
+ar palace walk [--depth identity|active|relevant|full]
+ar palace search <query>
+
+# 感知与洞察
+ar awareness read
+ar awareness update --insight "标题" --evidence "证据" --applies-when kw1,kw2
+ar insight <context> [--limit N]
+
+# 全局选项
+--root <path>     存储根目录（默认：~/.agent-recall）
+--project <slug>  项目覆盖
 ```
 
-### 核心机制
+---
 
-**扇出写入** — 写入一个房间，相关房间通过 `[[wikilinks]]` 自动更新交叉引用。机械式处理，零 LLM 成本。
+## 架构
 
-**显著性评分** — 每个房间有显著性分数：`重要性(0.4) + 时效性(0.3) + 访问频率(0.2) + 连接数(0.1)`。高显著性房间优先展示，低于阈值自动归档。
+### 五层记忆模型
+
+```
+L1: 工作记忆     journal_capture           「发生了什么」
+L2: 情景记忆     journal_write             「这意味着什么」
+L3: 记忆宫殿     palace_write / walk       「跨会话的知识」
+L4: 感知系统     awareness_update          「复合的洞察」
+L5: 洞察索引     recall_insight            「跨项目的经验」
+```
 
-**复合感知** — `awareness.md` 上限 200 行。新洞察加入时，相似的合并（增强），不相似的竞争（最低确认次数的被替换）。约束创造压缩，压缩创造复合。
+### 核心机制
 
-**跨项目洞察召回** — `insights-index.json` 通过关键词将洞察映射到场景。`recall_insight("构建质量检查")` 返回来自任何项目的相关教训。
+**扇出写入** — 写入一个房间，相关房间通过 `[[wikilinks]]` 自动更新交叉引用。零 LLM 成本。
 
-**Obsidian 兼容** — 每个宫殿文件都有 YAML frontmatter + `[[wikilinks]]`。将 `palace/` 作为 Obsidian vault 打开 → 图形视图展示房间连接。零 Obsidian 依赖。
+**显著性评分** — `重要性(0.4) + 时效性(0.3) + 访问频率(0.2) + 连接数(0.1)`。高显著性房间优先展示，低于阈值自动归档。
 
-### 智能距离协议
+**复合感知** — `awareness.md` 上限 200 行。新洞察与相似的合并（增强），与不相似的竞争（最低确认次数的被替换）。约束创造压缩，压缩创造复合。
 
-人类意图与智能体理解之间的差距是结构性的 — 源于不同的认知起源，不是临时的技术问题。
+**跨项目洞察召回** — 通过关键词将洞察映射到场景。`recall_insight("构建质量检查")` 返回来自任何项目的相关教训。
 
-| 差距 | 工具 | 机制 |
-|------|------|------|
-| 智能体误解意图 | `alignment_check` | 记录置信度 + 假设 → 人类在工作前纠正 |
-| 智能体与先前决策矛盾 | `nudge` | 发现矛盾 → 人类澄清 |
-| 智能体跨会话遗忘 | `palace_walk` | 从身份到完整上下文的渐进式加载 |
-| 智能体重复过去的错误 | `recall_insight` | 跨项目洞察在工作前自动呈现 |
+**Obsidian 兼容** — YAML frontmatter + `[[wikilinks]]`。将 `palace/` 作为 Obsidian vault 打开即可。零 Obsidian 依赖。
 
 ---
 
-## 设计理念
-
-**记忆不是目的，理解才是。**
+## 平台兼容性
 
-大多数记忆系统优化检索准确性。AgentRecall 优化**对齐准确性** — 缩小人类意图和智能体行为之间的差距。
+| 平台 | MCP | SDK | CLI | 说明 |
+|------|:---:|:---:|:---:|------|
+| Claude Code | ✅ | ✅ | ✅ | 完整支持 — MCP + 技能 + 命令 |
+| Cursor | ✅ | ✅ | ✅ | MCP via .cursor/mcp.json |
+| VS Code (Copilot) | ✅ | ✅ | ✅ | MCP via .vscode/mcp.json |
+| Windsurf | ✅ | ✅ | ✅ | MCP via mcp_config.json |
+| OpenAI Codex | ✅ | ✅ | ✅ | `codex mcp add` |
+| LangChain / CrewAI | — | ✅ | — | SDK 集成到你的 chain 中 |
+| Vercel AI SDK | — | ✅ | — | SDK 在 server actions 中使用 |
+| CI / GitHub Actions | — | — | ✅ | `npx agent-recall-cli` |
+| 任何 MCP 智能体 | ✅ | — | — | 标准 MCP 协议 |
 
-**复合优于累积。** 贴了更好标签的文件柜还是文件柜。AgentRecall 的感知系统在插入时强制合并：每个新洞察要么增强已有的，要么替换最弱的。100 个会话后，`awareness.md` 仍是 200 行 — 但每一行承载着经过确认和交叉验证的观察。
+---
 
-**默认跨项目。** 在一个项目中学到的洞察适用于所有项目。`recall_insight` 不关心教训来自哪个项目 — 它匹配当前场景和全局索引。
+## 文档
 
-**智能体友好，人类可见。** 一切都是磁盘上的 markdown。智能体通过 MCP 工具消费。人类在 Obsidian（或任何文本编辑器）中浏览。零云端、零遥测、零锁定。
+| 文档 | 说明 |
+|------|------|
+| [智能距离协议](docs/intelligent-distance-protocol.md) | 基础理论 — 人类与 AI 之间的差距是结构性的，如何导航 |
+| [MCP 适配器规范](docs/mcp-adapter-spec.md) | 基于 AgentRecall 构建适配器的技术规范 |
+| [SDK 设计](docs/sdk-design.md) | SDK 架构设计文档 |
+| [v3.4 升级说明](UPGRADE-v3.4.md) | 周报压缩、宫殿优先冷启动、提升验证 |
 
 ---
 
 ## 贡献
 
-由 [tongwu](https://github.com/Goldentrii) 构建。
+由 [tongwu](https://github.com/Goldentrii) 在 [Novada](https://www.novada.com) 构建。
 
 - Issues & 反馈：[GitHub Issues](https://github.com/Goldentrii/AgentRecall/issues)
-- 邮箱：tongwu0824@gmail.com
-- 协议规范：[docs/intelligent-distance-protocol.md](https://github.com/Goldentrii/AgentRecall/blob/main/docs/intelligent-distance-protocol.md)
+- 邮箱：[tong.wu@novada.com](mailto:tong.wu@novada.com)
+- 网站：[novada.com](https://www.novada.com)
 
 MIT 许可证。