zettelkasten-memory-server/README.md

基于 Zettelkasten 记忆片段盒方法的 MCP 记忆服务器 v1.6.X

# Zettelkasten Memory Server v1.3.10

基于 Zettelkasten 记忆片段盒方法的 MCP (Model Context Protocol) 记忆服务器，提供简化而强大的记忆片段化记忆管理功能。

## 🆕 v1.3.10 更新

- 🔧 **智能优化建议**: 重构 getOptimizeSuggestions 方法，提供更精准的低价值片段和孤立片段识别
- 📊 **信息散度计算**: 引入信息散度概念，更准确地评估记忆片段价值
- 🔒 **系统片段保护**: 增强系统片段的只读特性，防止意外修改
- 📝 **详细优化指南**: 提供具体的优化策略和操作步骤
- 🧪 **全面测试覆盖**: 新增测试文件，确保新方法的正确性和稳定性
- 🔄 **重复读取限制**: 新增重复读取限制机制，防止不必要的重复操作

## 设计理念

相比传统的记忆管理系统，本服务器采用了更加精简的 Zettelkasten 方法：

- **消除搜索开销**: 不提供复杂的搜索功能，避免提示词开销过大
- **记忆片段化存储**: 每个记忆都是独立的记忆片段，支持 `[[记忆片段名]]` 引用语法
- **自底向上**: 让知识结构自然呈现，而不是预设分类体系
- **权重计算**: 通过递归链接关系自动计算记忆片段重要性
- **优化建议**: 识别低价值记忆片段，协助维护系统健康

## 功能特性

### 核心操作
- `getMemory`: 获取记忆片段内容，支持递归展开引用
- `setMemory`: 创建或更新记忆片段内容
- `deleteMemory`: 删除记忆片段
- `renameMemory`: 重命名或合并记忆片段，自动更新所有引用

### 智能提示
- `getMemoryHints`: 获取按权重排序的重要记忆片段列表
- `getOptimizeSuggestions`: 获取记忆片段优化建议，包括低价值片段和孤立片段

### 资源访问
- **列出资源**: 自动列出所有记忆片段作为 MCP 资源
- **灵活访问**: 支持 `memory:///fragmentName#expandDepth` 格式，等效于 `getMemory(fragmentName, expandDepth)`

### 智能提示模板
- **话题灵感** (`topic_inspiration`): 当不知道聊什么话题时，基于重要记忆片段提供话题建议
- **聊天优化** (`chat_optimization`): 聊天结束时，提供系统优化建议和维护指导

## 安装和使用

### 安装依赖

```bash
npm install
```

### 构建项目

```bash
npm run build
```

### 启动服务器

```bash
npm start
```

或者直接运行：

```bash
node build/index.js
```

### 自定义存储目录

通过环境变量指定存储目录：

```bash
ZETTELKASTEN_STORAGE_DIR="/path/to/your/cards" npm start
```

### 重复读取限制机制

为了防止不必要的重复读取操作，系统引入了重复读取限制机制：

- **环境变量**: `MEMORY_REPEAT_ACCESS_RESTRICTION=true` 启用限制（默认启用）
- **机制说明**: 已获取最新内容的记忆片段无需重复 getMemory 操作
- **编辑操作影响**: 任何编辑操作（setMemory、extractMemory、insertLinkAt、renameMemory）后会移除最新内容标记
- **使用建议**: 编辑操作前必须先获取最新内容，否则操作会被拒绝

```bash
# 启用重复读取限制
MEMORY_REPEAT_ACCESS_RESTRICTION=true npm start

# 禁用重复读取限制
MEMORY_REPEAT_ACCESS_RESTRICTION=false npm start
```

## 记忆片段语法

### 基本记忆片段
每个记忆片段都是一个 `.md` 文件，内容可以是任意文本：

```markdown
这是一张关于 JavaScript 的记忆片段。

JavaScript 是一种编程语言，它有以下特点：
- 动态类型
- 原型继承
- 事件驱动

相关概念: [[编程语言]]、[[Web开发]]
```

### 引用语法
使用 `[[记忆片段名]]` 来引用其他记忆片段：

```markdown
今天学习了 [[React]]，它是基于 [[JavaScript]] 的前端框架。

React 的核心概念包括：
- [[组件化]]
- [[状态管理]]
- [[虚拟DOM]]
```

### 展开引用
使用 `getMemory` 工具时，可以指定展开深度来递归获取引用记忆片段的内容：

```typescript
// 展开深度为 1，会展开第一层引用的记忆片段内容
getMemory("React", 1)
```

展开后的内容格式：
```markdown
今天学习了 React，它是基于 JavaScript 的前端框架。

![[JavaScript]]start

JavaScript 是一种编程语言，它有以下特点：
- 动态类型
- 原型继承
- 事件驱动

![[JavaScript]]end

React 的核心概念包括：
- 组件化
- 状态管理
- 虚拟DOM
```

## 权重计算机制

系统会自动计算每个记忆片段的权重：

- **叶子记忆片段** (无外链): 权重 = 1
- **有外链的记忆片段**: 权重 = 所有引用记忆片段权重的平均值

这个机制让经常被引用的基础概念获得更高权重，有助于识别知识体系中的核心节点。

## 信息散度与优化建议

系统提供智能优化建议功能，通过信息散度计算和孤立片段识别来帮助维护知识库的健康。

### 信息散度概念

信息散度是衡量记忆片段价值的重要指标：

**信息散度 = 权重 / 字符数**

- **低信息散度**: 表示信息过于集中，可能需要拆分
  - 权重高但字符数少：信息密度过高，建议拆分为更小的概念单元
  - 权重低且字符数少：可能是孤立或无用的片段
- **高信息散度**: 表示信息分布合理，网络连接良好
  - 权重高且字符数适中：核心概念，保持现状
  - 权重低但字符数少：可能是新兴概念，需要更多连接

### 系统片段的只读特性

系统片段是知识库的核心组成部分，具有特殊的保护机制：

- **识别方法**: 内容以 `<!-- core memory -->` 开头的记忆片段
- **只读特性**: 无法通过 setMemory、extractMemory 等方法修改
- **保护目的**: 确保系统核心的稳定性和一致性
- **操作建议**: 如需修改系统相关内容，应在其他可编辑片段中进行操作

### getOptimizeSuggestions 工具详解

`getOptimizeSuggestions` 工具提供全面的记忆片段优化建议：

**参数:**
- `optimizationThreshold` (number, 可选): 优化阈值，默认为 0.1
- `maxFileCount` (number, 可选): 返回的记忆片段最大数量，默认为 10

**功能特点:**
1. **低价值片段识别**: 识别信息散度低于阈值的记忆片段
2. **孤立片段检测**: 发现没有反向链接的孤立记忆片段
3. **系统片段过滤**: 自动跳过系统片段，只分析可编辑内容
4. **优化策略建议**: 提供具体的优化步骤和操作指导

**返回内容:**
- 信息散度计算原理说明
- 孤立片段概念解释
- 系统片段保护机制说明
- 低价值片段列表及优化建议
- 孤立片段列表及处理策略
- 维护建议和推荐工具使用

## MCP 工具列表

### getMemory
获取指定记忆片段的内容，支持递归展开引用。

**参数:**
- `fragmentName` (string): 记忆片段名称
- `expandDepth` (number, 可选): 展开深度，默认为 0
- `withLineNumber` (boolean, 可选): 是否显示行号，默认为 false

### setMemory  
创建或更新记忆片段的内容。

**参数:**
- `fragmentName` (string): 记忆片段名称
- `content` (string): 记忆片段内容

### deleteMemory
删除指定的记忆片段。

**参数:**
- `fragmentName` (string): 要删除的记忆片段名称

### renameMemory
重命名记忆片段或将两个记忆片段合并。

**参数:**
- `oldFragmentName` (string): 原记忆片段名称  
- `newFragmentName` (string): 新记忆片段名称

### extractMemory
从现有记忆片段中提取内容创建新片段。

**参数:**
- `sourceFragmentName` (string): 源记忆片段名称
- `newFragmentName` (string): 新记忆片段名称
- `startLine` (number): 起始行号
- `endLine` (number): 结束行号

### getMemoryHints
获取按权重排序的重要记忆片段提示。

**参数:**
- `fileCount` (number, 可选): 返回的记忆片段数量，默认为 10

### getOptimizeSuggestions
获取记忆片段优化建议，包括低价值片段和孤立片段。

**参数:**
- `optimizationThreshold` (number, 可选): 优化阈值，默认为 0.1
- `maxFileCount` (number, 可选): 返回的记忆片段最大数量，默认为 10

**使用示例:**

```javascript
// 获取默认的优化建议
const suggestions = await tools.call("getOptimizeSuggestions");

// 自定义参数获取更详细的建议
const detailedSuggestions = await tools.call("getOptimizeSuggestions", {
  optimizationThreshold: 0.05,  // 更低的阈值，识别更多需要优化的片段
  maxFileCount: 20              // 返回更多建议
});
```

**优化策略示例:**

1. **低信息散度片段处理**:
   ```markdown
   # 原始片段 (需要拆分)
   这是一个包含多个概念的冗长记忆片段，包含了概念A、概念B和概念C...
   
   # 优化后
   # 概念A
   [概念A的详细内容]
   相关概念: [[概念B]]、[[概念C]]
   
   # 概念B
   [概念B的详细内容]
   相关概念: [[概念A]]
   
   # 概念C
   [概念C的详细内容]
   相关概念: [[概念A]]
   ```

2. **孤立片段处理**:
   ```markdown
   # 孤立片段
   这是一个没有其他记忆片段链接的内容...
   
   # 优化方法
   # 方法1: 在相关片段中添加链接
   在 [[相关概念]] 中添加: "更多信息可参考 [[孤立片段]]"
   
   # 方法2: 合并到相关片段
   将孤立片段的内容合并到 [[相关概念]] 中
   
   # 方法3: 删除无用片段
   如果内容不再需要，可直接删除
   ```

3. **系统片段注意事项**:
   ```markdown
   <!-- core memory -->
   # 系统片段
   这是系统核心内容，无法直接修改...
   
   # 正确操作方式
   # 1. 在其他可编辑片段中引用系统片段
   # 2. 使用 extractMemory 从系统片段中提取内容到新片段
   # 3. 在新片段中进行编辑操作
   ```

## 新特性说明

- getMemory 支持 withLineNumber 参数，输出带行号内容。
- getMemory 返回内容最大长度为 2k，超出会被截断并提示。
- 已获取最新内容的文件无需重复 getMemory，编辑操作前必须先获取最新内容，否则拒绝。
- 编辑操作（setMemory、extractMemory、insertLinkAt、renameMemory）后会移除最新内容标记。
- 新增重复读取限制机制，通过环境变量 MEMORY_REPEAT_ACCESS_RESTRICTION 控制。

## 最佳实践

### 1. 建立入口记忆片段
创建 `hints` 记忆片段作为系统的入口点：

```markdown
# 知识体系入口

## 编程相关
- [[JavaScript]]
- [[Python]]  
- [[算法与数据结构]]

## 项目管理
- [[项目规划]]
- [[团队协作]]

## 学习笔记
- [[今日学习]]
- [[问题记录]]
```

### 2. 保持记忆片段原子化
每张记忆片段只包含一个核心概念：

```markdown
# React Hooks

React Hooks 是 React 16.8 引入的新特性，让你可以在函数组件中使用状态和其他 React 特性。

常用的 Hooks：
- [[useState]]
- [[useEffect]]  
- [[useContext]]

相关概念：[[React]]、[[函数组件]]
```

### 3. 建立有意义的连接
不要只是罗列链接，要说明关系：

```markdown
# 设计模式

设计模式是软件设计中常用的解决方案。

## 创建型模式
- [[单例模式]] - 确保类只有一个实例
- [[工厂模式]] - 创建对象的接口

## 行为型模式  
- [[观察者模式]] - 用于 [[事件驱动编程]]

设计模式在 [[JavaScript]] 和 [[Python]] 中都有广泛应用。
```

### 4. 定期维护
使用 `getOptimizeSuggestions` 工具定期检查记忆片段，进行优化：

- **识别低价值片段**: 使用信息散度计算找出需要拆分的片段
- **发现孤立片段**: 找出没有链接的孤立内容
- **精简冗长内容**: 拆分过于复杂的记忆片段
- **删除过时信息**: 移除不再需要的孤立片段
- **增强连接性**: 在相关片段间建立有意义的链接
- **保护系统片段**: 避免直接修改系统核心内容

## 智能提示功能

### 话题灵感提示
当不知道聊什么话题时，使用 `topic_inspiration` 提示：

```bash
# 在 MCP 客户端中
请使用 "话题灵感" 提示模板
```

系统会：
1. 自动获取重要记忆片段
2. 按权重分类为核心话题、深度话题、轻松话题
3. 提供对话建议和操作指导

### 聊天优化提示
聊天结束时，使用 `chat_optimization` 提示：

```bash
# 在 MCP 客户端中
请使用 "聊天优化" 提示模板
```

系统会：
1. 分析当前知识库状态
2. 识别需要优化的低价值记忆片段
3. 提供具体的优化建议和行动计划
4. 给出系统健康度评估

### 提示功能优势
- **智能上下文**: 自动收集相关数据生成个性化提示
- **一键操作**: 复杂的分析任务变成简单的模板选择
- **引导学习**: 帮助发现知识网络中的机会和问题
- **持续优化**: 保持知识库的健康和高质量
- 合并相似内容
- 删除过时信息
- 改进内容质量

## 许可证

MIT License