agent-recall-mcp 2.1.2 → 2.1.3

package/README.md

@@ -1,15 +1,27 @@
 # agent-recall-mcp
 
-> Give your AI agent a brain that survives every session.
+> Persistent memory for AI agents. Session state that survives restarts, handoffs, and cold starts.
 
 [![npm](https://img.shields.io/npm/v/agent-recall-mcp?style=flat-square)](https://www.npmjs.com/package/agent-recall-mcp)
-[![License](https://img.shields.io/badge/license-MIT-brightgreen?style=flat-square)](../LICENSE)
+[![License](https://img.shields.io/badge/license-MIT-brightgreen?style=flat-square)](https://github.com/Goldentrii/AgentRecall/blob/main/LICENSE)
 [![MCP](https://img.shields.io/badge/MCP-9_tools-orange?style=flat-square)](#tools)
 [![Node](https://img.shields.io/badge/node-%3E%3D18-green?style=flat-square)](#requirements)
 
-MCP server for [AgentRecall](https://github.com/Goldentrii/AgentRecall) — two-layer session memory with Think-Execute-Reflect quality loops, alignment detection, and contradiction nudging. Works with any MCP-compatible agent: Claude Code, Cursor, VS Code Copilot, Windsurf, Claude Desktop, and more.
+**agent-recall-mcp** is an MCP server that gives any AI agent persistent session memory, alignment detection, and cross-session intelligence. Works with Claude Code, Cursor, VS Code Copilot, Windsurf, Claude Desktop, and any MCP-compatible client.
 
-**Zero cloud. Zero telemetry. All data stays local.**
+**Zero cloud. Zero telemetry. All data stays on your machine.**
+
+---
+
+## Why AgentRecall?
+
+| Problem | How AgentRecall solves it |
+|---------|--------------------------|
+| Agent forgets everything between sessions | Three-layer memory persists state across sessions |
+| Cold-start costs 2,000-5,000 tokens of context | Agent reads structured journal in ~200 tokens |
+| Human says one thing, agent builds another | Alignment checks measure the understanding gap |
+| Human contradicts a past decision unknowingly | Nudge protocol surfaces the contradiction |
+| Multi-agent handoff loses context | Machine-readable state transfers cleanly between agents |
 
 ---
 
@@ -49,9 +61,9 @@ claude mcp add agent-recall -- npx -y agent-recall-mcp
 }
 ```
 
-### Windsurf / Claude Desktop
+### Windsurf / Claude Desktop / Other MCP Clients
 
-Same pattern — add as an MCP server with `npx -y agent-recall-mcp` as the command.
+Add as an MCP server with command: `npx -y agent-recall-mcp`
 
 ---
 
@@ -65,7 +77,7 @@ Same pattern — add as an MCP server with `npx -y agent-recall-mcp` as the comm
 |------|-------------|
 | `journal_read` | Read entry by date or `"latest"`. Filter by section (`brief`, `qa`, `completed`, `status`, `blockers`, `next`, `decisions`, `reflection`, `files`, `observations`). |
 | `journal_write` | Append to or replace today's journal. Target a specific section or use `replace_all` for full overwrite. |
-| `journal_capture` | Lightweight Layer 1 Q&A capture — one question + answer pair, tagged, timestamped. Doesn't load the full journal. |
+| `journal_capture` | Lightweight Layer 1 Q&A capture — one question + answer pair, tagged, timestamped. |
 | `journal_list` | List recent entries for a project (date, title, momentum). |
 | `journal_search` | Full-text search across all journal entries. Filter by section. |
 | `journal_projects` | List all tracked projects on this machine. |
@@ -74,14 +86,32 @@ Same pattern — add as an MCP server with `npx -y agent-recall-mcp` as the comm
 
 | Tool | Description |
 |------|-------------|
-| `alignment_check` | Record what the agent understood, its confidence level, assumptions, and any human correction. Measures the understanding gap. |
+| `alignment_check` | Record what the agent understood, its confidence level, assumptions, and any human correction. Measures the understanding gap over time. |
 | `nudge` | Surface a contradiction between the human's current input and a prior decision. Helps the human clarify their own thinking. |
 
 ### Synthesis (Cross-Session Intelligence)
 
 | Tool | Description |
 |------|-------------|
-| `context_synthesize` | Generate L3 semantic synthesis from recent journals — goal evolution, decision history, active blockers, recurring patterns, contradiction detection. |
+| `context_synthesize` | Generate L3 semantic synthesis — goal evolution, decision history, active blockers, recurring patterns, and contradiction detection across sessions. |
+
+---
+
+## Three-Layer Memory Architecture
+
+```
+L1: Working Memory    [per-turn, ~50 tokens]    "What happened"
+    |  synthesized into
+L2: Episodic Memory   [daily journal, ~800 tok]  "What it means"
+    |  synthesized into
+L3: Semantic Memory   [cross-session, ~200 tok]  "What's true across sessions"
+    (contradiction detection + goal evolution tracking)
+```
+
+Each layer serves a different consumer:
+- **L1** captures raw events as they happen (fast, append-only)
+- **L2** structures the day's work into a navigable journal (agent reads this on cold start)
+- **L3** synthesizes patterns across sessions (detects contradictions, tracks goal drift)
 
 ---
 
@@ -96,27 +126,14 @@ Two MCP resources for browsing without tool calls:
 
 ---
 
-## Three-Layer Memory
-
-```
-L1: Working Memory    [per-turn, ~50 tokens]    "What happened"
-    ↓ synthesized into
-L2: Episodic Memory   [daily journal, ~800 tok]  "What it means"
-    ↓ synthesized into
-L3: Semantic Memory   [cross-session, ~200 tok]  "What's true across sessions"
-    (contradiction detection + goal evolution tracking)
-```
-
----
-
 ## Project Auto-Detection
 
 When `project = "auto"` (default), the server resolves the project by:
 
 1. `AGENT_RECALL_PROJECT` env var
-2. Git remote origin → repo name
-3. Git root directory → basename
-4. `package.json` → `name` field
+2. Git remote origin -> repo name
+3. Git root directory -> basename
+4. `package.json` -> `name` field
 5. Basename of current working directory
 
 ---
@@ -125,14 +142,14 @@ When `project = "auto"` (default), the server resolves the project by:
 
 ```
 ~/.agent-recall/                    (or $AGENT_RECALL_ROOT)
-├── config.json
-└── projects/
-    └── {project-slug}/
-        └── journal/
-            ├── index.md              ← auto-generated index
-            ├── YYYY-MM-DD.md         ← L2: daily journal
-            ├── YYYY-MM-DD-log.md     ← L1: raw Q&A capture
-            └── YYYY-MM-DD-alignment.md ← alignment checks + nudges
++-- config.json
++-- projects/
+    +-- {project-slug}/
+        +-- journal/
+            +-- index.md              <- auto-generated index
+            +-- YYYY-MM-DD.md         <- L2: daily journal
+            +-- YYYY-MM-DD-log.md     <- L1: raw Q&A capture
+            +-- YYYY-MM-DD-alignment.md <- alignment checks + nudges
 ```
 
 **Legacy support**: automatically reads existing journals from `~/.claude/projects/*/memory/journal/`. New writes go to `~/.agent-recall/`.
@@ -167,177 +184,21 @@ npx agent-recall-mcp --list-tools # List all 9 tools as JSON
 
 ## Part of AgentRecall
 
-This MCP server is one component of the [AgentRecall](https://github.com/Goldentrii/AgentRecall) system:
-
-- **SKILL.md** — Claude Code skill with Think-Execute-Reflect quality loops
-- **agent-recall-mcp** — This MCP server (works with any agent)
-- **Intelligent Distance Protocol** — The underlying theory
-
----
-
-## License
-
-MIT — [Tongwu](https://github.com/Goldentrii)
-
----
-
----
-
-# agent-recall-mcp（中文文档）
-
-> 给你的 AI 智能体一个跨会话记忆的大脑。
-
-[AgentRecall](https://github.com/Goldentrii/AgentRecall) 的 MCP 服务器 — 双层会话记忆，Think-Execute-Reflect 质量循环，对齐检测，矛盾提醒。兼容所有 MCP 客户端：Claude Code、Cursor、VS Code Copilot、Windsurf、Claude Desktop 等。
-
-**零云端。零遥测。所有数据保存在本地。**
-
----
-
-## 快速开始
-
-### Claude Code
-
-```bash
-claude mcp add agent-recall -- npx -y agent-recall-mcp
-```
-
-### Cursor
-
-`.cursor/mcp.json`：
-```json
-{
-  "mcpServers": {
-    "agent-recall": {
-      "command": "npx",
-      "args": ["-y", "agent-recall-mcp"]
-    }
-  }
-}
-```
-
-### VS Code
-
-`.vscode/mcp.json`：
-```json
-{
-  "servers": {
-    "agent-recall": {
-      "command": "npx",
-      "args": ["-y", "agent-recall-mcp"]
-    }
-  }
-}
-```
-
----
-
-## 9 个工具
-
-### 日志（会话记忆）
-
-| 工具 | 功能 |
-|------|------|
-| `journal_read` | 按日期或 `"latest"` 读取日志。支持按章节过滤（`brief`、`qa`、`completed`、`status`、`blockers`、`next`、`decisions`、`reflection`、`files`、`observations`）。 |
-| `journal_write` | 追加或替换今日日志。可指定目标章节，或用 `replace_all` 全量覆写。 |
-| `journal_capture` | 轻量 Layer 1 问答捕获 — 一个问题+答案，带标签和时间戳。不加载完整日志。 |
-| `journal_list` | 列出项目的最近日志条目（日期、标题、状态）。 |
-| `journal_search` | 全文搜索所有日志条目，可按章节过滤。 |
-| `journal_projects` | 列出本机所有被追踪的项目。 |
-
-### 对齐（智能距离）
-
-| 工具 | 功能 |
-|------|------|
-| `alignment_check` | 记录智能体的理解、置信度、假设和人类的纠正。量化理解差距。 |
-| `nudge` | 检测到人类当前输入与之前的决策矛盾时，主动提问帮助人类理清思路。 |
-
-### 合成（跨会话智能）
-
-| 工具 | 功能 |
-|------|------|
-| `context_synthesize` | 从近期日志生成 L3 语义合成 — 目标演变、决策历史、活跃阻碍、重复模式、矛盾检测。 |
-
----
-
-## 资源（Resources）
+This MCP server is one component of the [AgentRecall](https://github.com/Goldentrii/AgentRecall) ecosystem:
 
-| URI 模式 | 说明 |
-|----------|------|
-| `agent-recall://{project}/index` | 项目日志索引 |
-| `agent-recall://{project}/{date}` | 指定日期的日志条目 |
+- **[SKILL.md](https://github.com/Goldentrii/AgentRecall/blob/main/SKILL.md)** — Claude Code skill with Think-Execute-Reflect quality loops
+- **[agent-recall-mcp](https://www.npmjs.com/package/agent-recall-mcp)** — This MCP server (works with any MCP agent)
+- **[Intelligent Distance Protocol](https://github.com/Goldentrii/AgentRecall/blob/main/docs/intelligent-distance-protocol.md)** — The underlying theory
 
 ---
 
-## 三层记忆架构
+## Feedback & Contributing
 
-```
-L1: 工作记忆    [每轮, ~50 tokens]    "发生了什么"
-    ↓ 合成为
-L2: 情景记忆    [每日日志, ~800 tok]   "这意味着什么"
-    ↓ 合成为
-L3: 语义记忆    [跨会话, ~200 tok]     "跨会话的真相"
-    （矛盾检测 + 目标演变追踪）
-```
-
----
-
-## 项目自动识别
-
-`project = "auto"`（默认）时，按以下优先级识别项目：
-
-1. `AGENT_RECALL_PROJECT` 环境变量
-2. Git 远程 origin → 仓库名
-3. Git 根目录 → 目录名
-4. `package.json` → `name` 字段
-5. 当前工作目录的 basename
+- Issues & PRs: [github.com/Goldentrii/AgentRecall](https://github.com/Goldentrii/AgentRecall)
+- Email: tongwu0824@gmail.com
 
 ---
 
-## 存储结构
-
-```
-~/.agent-recall/                    （或 $AGENT_RECALL_ROOT）
-├── config.json
-└── projects/
-    └── {project-slug}/
-        └── journal/
-            ├── index.md              ← 自动生成索引
-            ├── YYYY-MM-DD.md         ← L2: 每日日志
-            ├── YYYY-MM-DD-log.md     ← L1: 原始问答捕获
-            └── YYYY-MM-DD-alignment.md ← 对齐检查 + 矛盾提醒
-```
-
-**向后兼容**：自动读取 `~/.claude/projects/*/memory/journal/` 中的旧日志。新写入默认到 `~/.agent-recall/`。
-
----
-
-## 环境变量
-
-| 变量 | 默认值 | 说明 |
-|------|--------|------|
-| `AGENT_RECALL_ROOT` | `~/.agent-recall` | 存储根目录 |
-| `AGENT_RECALL_PROJECT` | （自动识别） | 覆盖项目标识 |
-
----
-
-## AgentRecall 生态
-
-此 MCP 服务器是 [AgentRecall](https://github.com/Goldentrii/AgentRecall) 系统的组件之一：
-
-- **SKILL.md** — Claude Code 技能，包含 Think-Execute-Reflect 质量循环
-- **agent-recall-mcp** — 本 MCP 服务器（兼容任意智能体）
-- **智能距离协议（Intelligent Distance Protocol）** — 底层理论框架
-
----
-
-## 核心理念
-
-**记忆解决遗忘，AgentRecall 解决误解。**
-
-人类和 AI 之间的理解差距是结构性的 — 人类说话前后矛盾、碎片化、含糊不清；AI 则以完美的自信构建错误的东西。AgentRecall 通过对齐检测、矛盾提醒和跨会话合成来弥合这个「智能距离」。
-
----
-
-## 许可证
+## License
 
 MIT — [Tongwu](https://github.com/Goldentrii)

package/dist/index.js

@@ -11,7 +11,7 @@ const execFileAsync = promisify(execFile);
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
-const VERSION = "2.1.0";
+const VERSION = "2.1.3";
 const JOURNAL_ROOT = process.env.AGENT_RECALL_ROOT ||
     path.join(os.homedir(), ".agent-recall");
 const LEGACY_ROOT = path.join(os.homedir(), ".claude", "projects");

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-recall-mcp",
-  "version": "2.1.2",
-  "description": "AI session memory with Think-Execute-Reflect quality loops — give your agent a brain that survives every session",
+  "version": "2.1.3",
+  "description": "Persistent agent memory and alignment detection via MCP — session state, contradiction nudging, and cross-session intelligence for any AI agent",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
@@ -23,18 +23,25 @@
     "mcp",
     "mcp-server",
     "model-context-protocol",
-    "agent-recall",
+    "agent-memory",
     "ai-memory",
+    "ai-session-persistence",
+    "agent-recall",
     "session-memory",
-    "journal",
+    "agent-to-agent",
     "ai-agents",
     "claude-code",
     "cursor",
+    "vscode",
+    "windsurf",
     "intelligent-distance",
+    "alignment-detection",
+    "contradiction-detection",
     "quality-loop",
     "think-execute-reflect",
-    "agent-memory",
-    "cold-start"
+    "cold-start",
+    "journal",
+    "cross-session"
   ],
   "license": "MIT",
   "repository": {