agent-recall-mcp 3.2.2 → 3.3.1

package/README.md

@@ -7,7 +7,7 @@
 <p align="center">
   <a href="https://www.npmjs.com/package/agent-recall-mcp"><img src="https://img.shields.io/npm/v/agent-recall-mcp?style=flat-square&color=5D34F2" alt="npm"></a>
   <a href="https://github.com/NovadaLabs/AgentRecall/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-brightgreen?style=flat-square" alt="License"></a>
-  <img src="https://img.shields.io/badge/MCP-12_tools-orange?style=flat-square" alt="Tools">
+  <img src="https://img.shields.io/badge/MCP-14_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">
 </p>
@@ -85,7 +85,7 @@ Say **"save"** to journal. Say **"read the latest journal"** to resume.
 
 ---
 
-## 12 MCP Tools
+## 14 MCP Tools
 
 ### Session Memory (6 tools)
 
@@ -106,6 +106,13 @@ Say **"save"** to journal. Say **"read the latest journal"** to resume.
 | `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 |
 
+### Knowledge Loop (2 tools) — NEW
+
+| 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. |
+
 ### Alignment & Synthesis (3 tools)
 
 | Tool | Purpose |
@@ -229,3 +236,156 @@ Built by [tongwu](https://github.com/Goldentrii) at [NovadaLabs](https://github.
 MIT — *Concept & Design: [tongwu](https://github.com/Goldentrii)*
 
 **Memory solves forgetting. AgentRecall solves misunderstanding.**
+
+---
+
+---
+
+# agent-recall-mcp（中文文档）
+
+> 给你的 AI 智能体一个跨会话记忆的大脑。
+
+---
+
+## 智能距离（Intelligent Distance）— 核心理念
+
+> *「人类智能与 AI 智能之间的差距是结构性的、永久的 — 不是一个临时的技术问题。」*
+
+人类是「生出来的」（具身经验、情感、生存压力）。机器是「造出来的」（规则、确定性）。AI 是「训练出来的」（数据上的统计共现）。三种不同的认知起源，产生三种不同的理解方式。这个差距不会随 AI 进步而消失 — 因为差异在于**起源**，而非能力。
+
+```
+人类说：「全部点击」
+AI 理解：「点击主要的」
+差距：「全部」≠「主要的」
+
+人类说：「做完意味着完全一样」
+AI 认为：「差不多就行」
+差距：「完全一样」≠「差不多」
+
+人类给出：零散、非线性的指令
+AI 选择：一条指令，忽略其余
+差距：点与点之间的逻辑关联丢失了
+```
+
+**AgentRecall 不试图缩小这个差距，而是构建一个协议来导航它。**
+
+---
+
+## AgentRecall 如何弥合差距
+
+| 智能距离缺口 | AgentRecall 工具 | 功能 |
+|-------------|-----------------|------|
+| 智能体忘了人类昨天说的话 | `journal_read` + `journal_cold_start` | 三层记忆 + 缓存感知冷启动 |
+| 智能体误解人类意图 | `alignment_check` | 记录置信度 + 假设 → 人类在工作开始前纠正 |
+| 智能体与之前的决策矛盾 | `nudge` | 检测矛盾 → 在造成损失前提出 |
+| 智能体说「完成了」但人类不同意 | Think-Execute-Reflect 循环 | 用数字评分（「建了 11 页 35 个标签」），不用感觉（「做得不错」）|
+| 智能体凭想象构建，而非基于数据 | `journal_state` (JSON) | agent 间结构化交接 — 毫秒级，无需解析散文 |
+| 智能体重复同样的错误 | 失败记录 + `context_synthesize` | 跨会话模式检测 → 提升为永久记忆 |
+| 下一个 agent 从零开始 | `journal_cold_start` (v3) | 热/温/冷缓存 — 加载 3 个文件而非 28 个 |
+
+**记忆解决遗忘，AgentRecall 解决误解。**
+
+---
+
+## 快速开始
+
+```bash
+# Claude Code
+claude mcp add agent-recall -- npx -y agent-recall-mcp
+
+# 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"] } } }
+```
+
+---
+
+## 14 个工具
+
+### 会话记忆（6 个）
+
+| 工具 | 功能 |
+|------|------|
+| `journal_read` | 按日期读取日志，支持章节过滤 |
+| `journal_write` | 追加或替换今日日志 |
+| `journal_capture` | 轻量问答捕获 |
+| `journal_list` | 列出最近日志 |
+| `journal_search` | 全文搜索 |
+| `journal_projects` | 列出所有项目 |
+
+### v3 架构（3 个）— 新增
+
+| 工具 | 功能 |
+|------|------|
+| `journal_state` | **JSON 状态层** — 结构化读写，agent 间毫秒级交接 |
+| `journal_cold_start` | **缓存感知冷启动** — 热（0-1天）/ 温（2-7天）/ 冷（7天+） |
+| `journal_archive` | **归档旧条目** — 移至 archive/，保留单行摘要 |
+
+### 知识循环（2 个）— 新增
+
+| 工具 | 功能 |
+|------|------|
+| `knowledge_write` | **写入永久教训** — 按类别结构化记录（提取、构建、验证、工具、通用）。Agent 从过去的错误中学习。 |
+| `knowledge_read` | **读取过去教训** — 按项目、类别或搜索词过滤。Agent 开始工作前检查过去的失败。 |
+
+### 对齐 & 合成（3 个）
+
+| 工具 | 功能 |
+|------|------|
+| `alignment_check` | 记录理解度、置信度、假设、人类纠正 |
+| `nudge` | 检测矛盾，主动提问 |
+| `context_synthesize` | 跨会话合成：目标演变、决策历史、模式检测 |
+
+---
+
+## 三层记忆 + v3 缓存
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ L1: 工作记忆    [每轮, ~50 tok]     「发生了什么」        │
+│     ↓ 合成为                                             │
+│ L2: 情景记忆    [每日日志, ~800 tok] 「这意味着什么」      │
+│     ↓ 合成为                                             │
+│ L3: 语义记忆    [跨会话]            「跨会话的真相」       │
+│     （矛盾检测 + 目标演变追踪）                           │
+├─────────────────────────────────────────────────────────┤
+│ v3: JSON 状态层  [每会话]  agent 间结构化数据              │
+├─────────────────────────────────────────────────────────┤
+│ v3: 缓存层       热（0-1天）→ 温（2-7天）→ 冷（7天+）    │
+│     journal_cold_start → 加载 3 个文件而非 28 个          │
+└─────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Think-Execute-Reflect 质量循环
+
+```
+🧠 THINK    → 方法对吗？做了调研吗？
+⚡ EXECUTE  → 实际 vs 计划？（用数字，不用感觉）
+🔍 REFLECT  → 5 维度质量评分 + 智能距离差距分析
+🔄 FEEDBACK → 循环（需要迭代）或 退出（质量足够）
+```
+
+**Reflect 步骤显式测量智能距离：**
+- 用户意图 vs 我的理解
+- 两者之间的差距（或「无 — 已对齐」）
+- 下次如何缩小差距
+
+---
+
+## 反馈 & 贡献
+
+由 [tongwu](https://github.com/Goldentrii) 在 [NovadaLabs](https://github.com/NovadaLabs) 构建。
+
+**我们期待你的反馈：**
+- 邮箱：tongwu0824@gmail.com
+- GitHub Issues：[NovadaLabs/AgentRecall](https://github.com/NovadaLabs/AgentRecall/issues)
+
+---
+
+## 许可证
+
+MIT — [tongwu](https://github.com/Goldentrii) @ [NovadaLabs](https://github.com/NovadaLabs)

package/dist/helpers/journal-files.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Journal file listing, reading, and index maintenance.
+ */
+import type { JournalEntry } from "../types.js";
+/**
+ * List all .md journal files across all directories for a project.
+ * Returns sorted array with most recent first.
+ */
+export declare function listJournalFiles(project: string): JournalEntry[];
+/**
+ * Read a journal file. Checks primary dir first, then legacy.
+ */
+export declare function readJournalFile(project: string, date: string): string | null;
+/**
+ * Extract title from journal file content.
+ */
+export declare function extractTitle(content: string): string;
+/**
+ * Extract momentum indicator from journal content.
+ */
+export declare function extractMomentum(content: string): string;
+/**
+ * Count entries in a log file (for journal_capture entry numbering).
+ */
+export declare function countLogEntries(logPath: string): number;
+/**
+ * Update the index.md for a project.
+ */
+export declare function updateIndex(project: string): void;
+//# sourceMappingURL=journal-files.d.ts.map

package/dist/helpers/journal-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"journal-files.d.ts","sourceRoot":"","sources":["../../src/helpers/journal-files.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,EAAE,CAmBhE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAa5E;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAGpD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAOvD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAKvD;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAuBjD"}

package/dist/helpers/journal-files.js

@@ -0,0 +1,96 @@
+/**
+ * Journal file listing, reading, and index maintenance.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { journalDir, journalDirs } from "../storage/paths.js";
+import { ensureDir } from "../storage/fs-utils.js";
+/**
+ * List all .md journal files across all directories for a project.
+ * Returns sorted array with most recent first.
+ */
+export function listJournalFiles(project) {
+    const dirs = journalDirs(project);
+    const entries = [];
+    const seen = new Set();
+    for (const dir of dirs) {
+        if (!fs.existsSync(dir))
+            continue;
+        const files = fs.readdirSync(dir);
+        for (const file of files) {
+            const match = file.match(/^(\d{4}-\d{2}-\d{2})\.md$/);
+            if (match && !seen.has(match[1])) {
+                seen.add(match[1]);
+                entries.push({ date: match[1], file, dir });
+            }
+        }
+    }
+    entries.sort((a, b) => b.date.localeCompare(a.date));
+    return entries;
+}
+/**
+ * Read a journal file. Checks primary dir first, then legacy.
+ */
+export function readJournalFile(project, date) {
+    const filename = `${date}.md`;
+    const dirs = journalDirs(project);
+    const primaryDir = journalDir(project);
+    const allDirs = [primaryDir, ...dirs.filter((d) => d !== primaryDir)];
+    for (const dir of allDirs) {
+        const filePath = path.join(dir, filename);
+        if (fs.existsSync(filePath)) {
+            return fs.readFileSync(filePath, "utf-8");
+        }
+    }
+    return null;
+}
+/**
+ * Extract title from journal file content.
+ */
+export function extractTitle(content) {
+    const match = content.match(/^# (.+)$/m);
+    return match ? match[1].trim() : "(untitled)";
+}
+/**
+ * Extract momentum indicator from journal content.
+ */
+export function extractMomentum(content) {
+    const patterns = [/[🟢🟡🔴⚪]\s*\S+/];
+    for (const pattern of patterns) {
+        const match = content.match(pattern);
+        if (match)
+            return match[0];
+    }
+    return "";
+}
+/**
+ * Count entries in a log file (for journal_capture entry numbering).
+ */
+export function countLogEntries(logPath) {
+    if (!fs.existsSync(logPath))
+        return 0;
+    const content = fs.readFileSync(logPath, "utf-8");
+    const matches = content.match(/^### Q\d+/gm);
+    return matches ? matches.length : 0;
+}
+/**
+ * Update the index.md for a project.
+ */
+export function updateIndex(project) {
+    const dir = journalDir(project);
+    ensureDir(dir);
+    const indexPath = path.join(dir, "index.md");
+    const entries = listJournalFiles(project);
+    let index = `# ${project} — Journal Index\n\n`;
+    index += `> Auto-generated. ${entries.length} entries.\n\n`;
+    index += `| Date | Title | Momentum |\n`;
+    index += `|------|-------|----------|\n`;
+    for (const entry of entries) {
+        const content = fs.readFileSync(path.join(entry.dir, entry.file), "utf-8");
+        const title = extractTitle(content);
+        const momentum = extractMomentum(content);
+        index += `| ${entry.date} | ${title} | ${momentum} |\n`;
+    }
+    fs.writeFileSync(indexPath, index, "utf-8");
+}
+//# sourceMappingURL=journal-files.js.map

package/dist/helpers/journal-files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"journal-files.js","sourceRoot":"","sources":["../../src/helpers/journal-files.ts"],"names":[],"mappings":"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"}

package/dist/helpers/sections.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Markdown section extraction and manipulation.
+ */
+/**
+ * Extract a section from a markdown journal entry.
+ */
+export declare function extractSection(content: string, section: string): string | null;
+/**
+ * Append content to a specific section in a journal file, or to end of file.
+ */
+export declare function appendToSection(existingContent: string, newContent: string, section: string | null): string;
+//# sourceMappingURL=sections.d.ts.map

package/dist/helpers/sections.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sections.d.ts","sourceRoot":"","sources":["../../src/helpers/sections.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH;;GAEG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAsC9E;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,eAAe,EAAE,MAAM,EACvB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,GAAG,IAAI,GACrB,MAAM,CA0CR"}

package/dist/helpers/sections.js

@@ -0,0 +1,84 @@
+/**
+ * Markdown section extraction and manipulation.
+ */
+import { SECTION_HEADERS } from "../types.js";
+/**
+ * Extract a section from a markdown journal entry.
+ */
+export function extractSection(content, section) {
+    if (section === "all")
+        return content;
+    if (section === "brief") {
+        const lines = content.split("\n");
+        const nonEmpty = [];
+        let pastTitle = false;
+        for (const line of lines) {
+            if (line.startsWith("# ")) {
+                pastTitle = true;
+                continue;
+            }
+            if (!pastTitle)
+                continue;
+            const trimmed = line.trim();
+            if (trimmed === "")
+                continue;
+            nonEmpty.push(trimmed);
+            if (nonEmpty.length >= 4)
+                break;
+        }
+        return nonEmpty.join("\n") || null;
+    }
+    const header = SECTION_HEADERS[section];
+    if (!header)
+        return null;
+    const idx = content.indexOf(header);
+    if (idx === -1)
+        return null;
+    const afterHeader = content.slice(idx);
+    const lines = afterHeader.split("\n");
+    const result = [lines[0]];
+    let inCodeFence = false;
+    for (let i = 1; i < lines.length; i++) {
+        if (lines[i].startsWith("```"))
+            inCodeFence = !inCodeFence;
+        if (!inCodeFence && lines[i].startsWith("## "))
+            break;
+        result.push(lines[i]);
+    }
+    return result.join("\n").trimEnd();
+}
+/**
+ * Append content to a specific section in a journal file, or to end of file.
+ */
+export function appendToSection(existingContent, newContent, section) {
+    if (section === "replace_all") {
+        return newContent;
+    }
+    if (!section) {
+        return existingContent.trimEnd() + "\n\n" + newContent + "\n";
+    }
+    const header = SECTION_HEADERS[section];
+    if (!header) {
+        return existingContent.trimEnd() + "\n\n" + newContent + "\n";
+    }
+    const idx = existingContent.indexOf(header);
+    if (idx === -1) {
+        return (existingContent.trimEnd() + "\n\n" + header + "\n\n" + newContent + "\n");
+    }
+    const afterHeader = existingContent.slice(idx);
+    const lines = afterHeader.split("\n");
+    let insertAt = lines.length;
+    let inCodeFence = false;
+    for (let i = 1; i < lines.length; i++) {
+        if (lines[i].startsWith("```"))
+            inCodeFence = !inCodeFence;
+        if (!inCodeFence && lines[i].startsWith("## ")) {
+            insertAt = i;
+            break;
+        }
+    }
+    const before = existingContent.slice(0, idx + lines.slice(0, insertAt).join("\n").length);
+    const after = existingContent.slice(idx + lines.slice(0, insertAt).join("\n").length);
+    return before.trimEnd() + "\n\n" + newContent + "\n" + after;
+}
+//# sourceMappingURL=sections.js.map

package/dist/helpers/sections.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sections.js","sourceRoot":"","sources":["../../src/helpers/sections.ts"],"names":[],"mappings":"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"}