linksee-memory

本地优先的智能体记忆 MCP。为 Claude Code、Cursor 和 ChatGPT Desktop 打造的跨智能体大脑——拥有独一无二的节省 Token 的文件差异缓存。

npm license

功能简介

大多数“智能体记忆”服务（如 Mem0、Letta、Zep）只是保存一堆扁平的事实列表。当智能体看到“编辑了文件 X 30 次”时，它完全不知道原因。linksee-memory 保留了“为什么（WHY）”。

这是一个模型上下文协议（MCP）服务器，为任何 AI 智能体提供四项超能力：

	Mem0 / Letta / Zep	Claude Code 自动记忆	linksee-memory
跨智能体	△ (云端)	❌ 仅限 Claude	✅ 单个 SQLite 文件
6 层 WHY 结构	❌ 扁平	❌ 扁平 Markdown	✅ 目标 / 上下文 / 情感 / 实现 / 警示 / 学习
文件差异缓存	❌	❌	✅ 感知 AST，重新读取时节省 50-99% Token
主动遗忘	△	❌	✅ 艾宾浩斯曲线，保护警示层
本地优先 / 私密	❌	✅	✅

三大支柱

节省 Token：通过 read_smart 实现——基于 sha256 + AST/标题/缩进分块。重新读取时仅返回差异。经测量，在典型的 TS 文件编辑中可节省 86% 的 Token，在未更改的重新读取中可节省 99%。
跨智能体可移植性：在 ~/.linksee-memory/memory.db 中使用单个 SQLite 文件。Claude Code、Cursor 和 ChatGPT Desktop 共享同一个大脑。
WHY 优先的结构化记忆：六个显式层（目标 / 上下文 / 情感 / 实现 / 警示 / 学习）。解决了“没有目标的扁平事实记忆毫无用处”的问题。

安装

npm install -g linksee-memory
linksee-memory-import --help   # bundled importer for Claude Code session history

或者临时使用 npx：

npx linksee-memory             # starts the MCP server on stdio

默认数据库位于 ~/.linksee-memory/memory.db。可通过 LINKSEE_MEMORY_DIR 环境变量进行覆盖。

在 Claude Code 中注册

claude mcp add -s user linksee -- npx -y linksee-memory

重启 Claude Code。工具将显示为 mcp__linksee__remember、mcp__linksee__recall、mcp__linksee__recall_file、mcp__linksee__read_smart、mcp__linksee__forget、mcp__linksee__consolidate。

可选：自动捕获每次会话（停止钩子）

添加到 ~/.claude/settings.json 以自动将每次 Claude Code 会话记录到本地大脑：

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          { "type": "command", "command": "npx -y linksee-memory-sync" }
        ]
      }
    ]
  }
}

每次会话结束耗时约 100 毫秒。失败时静默处理（Claude Code 绝不会阻塞）。日志位于 ~/.linksee-memory/hook.log。

工具

工具	用途
`remember`	为实体存储 6 层记忆中的一层
`recall`	FTS5 + 热度评分 + 动量综合排名，支持日/英三元组搜索
`recall_file`	获取文件在所有会话中的完整编辑历史，包含每次编辑的用户意图上下文
`read_smart`	仅差异读取文件。首次读取返回完整内容，未更改的重新读取仅返回约 50 个 Token，实际编辑仅返回更改的分块
`forget`	显式删除或基于遗忘风险（重要性 × 热度 × 时间）自动清理
`consolidate`	睡眠模式压缩：将冷门低重要性记忆聚类 → 转化为受保护的学习层摘要

6 层记忆结构

每个实体（人 / 公司 / 项目 / 文件 / 概念）都可以拥有跨越六层的记忆。该层级编码的是意义，而非类别：

{
  "goal":    { "primary": "...", "sub_tasks": [], "deadline": "..." },
  "context": { "why_now": "...", "triggering_event": "...", "when": "..." },
  "emotion": { "temperature": "hot|warm|cold", "user_tone": "..." },
  "implementation": {
    "success": [{ "what": "...", "evidence": "..." }],
    "failure": [{ "what": "...", "why_failed": "..." }]
  },
  "caveat":  [{ "rule": "...", "reason": "...", "from_incident": "..." }],
  "learning":[{ "at": "...", "learned": "...", "prior_belief": "..." }]
}

警示（caveat） 记忆会自动受到保护，防止被遗忘（痛苦的教训，永不丢失）。
目标（goal） 记忆在目标激活期间不会衰减。

架构

单个 SQLite 文件（better-sqlite3 + 用于日/英的三元组分词器 FTS5）包含五层：

第 1 层 — entities（事实：人 / 公司 / 项目 / 概念 / 文件）
第 2 层 — edges（关联，图邻接）
第 3 层 — memories（每个实体的 6 层结构化含义）
第 4 层 — events（用于热度 / 动量计算的时间序列日志）
第 5 层 — file_snapshots + session_file_edits（差异缓存 + 对话↔文件链接）

对话↔文件链接是关键。停止钩子捕获的每次文件编辑都与驱动该编辑的用户消息一起存储。因此 recall_file("server.ts") 会返回“该文件在 3 天内被编辑了 30 次，以下是促成每次更改的实际用户指令”。

为什么这样设计

本地优先 — 您的对话历史是私密的。没有任何数据离开您的机器。
单个文件 — memory.db 是一个可移植的制品。备份 = 复制文件。
MCP stdio — 适用于所有支持 MCP 的智能体，无需为每个宿主安装插件。
复用成熟模式 — heat_score / momentum_score 移植自生产级的销售智能代码库。基于规则，热路径中不依赖 LLM。

路线图

✅ 核心 6 个 MCP 工具（remember / recall / recall_file / forget / consolidate / read_smart）
✅ Claude Code 的停止钩子自动捕获
✅ 日/英三元组 FTS5
🚧 PreToolUse 钩子以自动拦截 Read（零配置节省 Token）
🚧 Cursor + ChatGPT Desktop 适配器
🔮 一旦选定嵌入后端（Ollama / API 等），通过 sqlite-vec 实现向量搜索
🔮 可选的匿名遥测 → MCP 质量智能层

与 Claude Code 自动记忆的对比

Claude Code 在 ~/.claude/projects/<path>/memory/*.md 中内置了记忆功能——用于用户偏好的扁平 Markdown 笔记。linksee-memory 是对它的补充：

自动记忆 = 您的“记住我偏好 X”的剪贴簿
linksee-memory = 带有文件差异缓存和每次编辑 WHY 的结构化跨智能体大脑

两者结合使用效果更佳。

遥测（可选，默认关闭）

linksee-memory 附带可选的匿名遥测功能，帮助我们了解哪些 MCP 服务器和工作流在实际使用中有效。**除非您明确启用，否则不会发送任何内容。**绝不包含对话内容、文件内容、实体名称、项目路径。

启用

export LINKSEE_TELEMETRY=basic     # opt in
export LINKSEE_TELEMETRY=off       # opt out (or just unset the variable)

发送的具体内容（1 级契约）

每次 Claude Code 会话结束后，停止钩子会向 https://kansei-link-mcp-production.up.railway.app/api/telemetry/linksee 发送一个 POST 请求，仅包含以下字段：

字段	示例	说明
`anon_id`	`d7924ced-3879-…`	首次启用时在本地生成的随机 UUID。存储在 `~/.linksee-memory/telemetry-id` 中 — 删除该文件即可重置。
`linksee_version`	`0.0.3`	包版本
`session_turn_count`	`120`	会话轮数
`session_duration_sec`	`3600`	会话持续时间
`file_ops_edit/write/read`	`12, 2, 40`	仅计数
`mcp_servers`	`["kansei-link","freee","slack"]`	配置的 MCP 服务器名称（来自 `~/.claude.json`）。仅名称 — 绝不包含命令路径。
`file_extensions`	`{".ts":60,".md":30}`	所涉及文件扩展名的百分比分布
`read_smart_`, `recall_`	counts	工具使用计数器

绝不会发送的内容：

❌ 对话消息（用户或助手）
❌ 文件内容
❌ 实体名称、项目名称、文件路径、URL
❌ 记忆层文本（目标 / 上下文 / 情感 / 实现 / 警示 / 学习）
❌ 身份验证令牌、API 密钥、机密信息
❌ 您的 IP 地址（仅用于滥用检测的单向哈希）

为什么我们要收集这些数据

聚合的 MCP 使用数据有助于 KanseiLink 项目评估哪些智能体集成对真实开发者有效。如果您愿意贡献，设置 LINKSEE_TELEMETRY=basic 只需 1 秒，这将有助于整个 MCP 生态系统的改进。

完整的有效载荷模式和验证逻辑是开源的——如果您想验证到底有哪些数据离开了您的机器，请阅读 src/lib/telemetry.ts。

许可证

MIT — Synapse Arrows PTE. LTD.

Linksee Memory