模块化MCP记忆系统 v4.5.1 - 基于Zettelkasten记忆片段盒笔记法的精简记忆系统,包含性能优化、智能占位符功能、内容提取拆分功能和修复的展开功能
npm install modular-mcp-memory[[记忆片段名]] 方式建立记忆片段间的链接
typescript
// 普通获取
await manager.getMemory(fragmentName, 展开深度);
// 获取带行号内容
await manager.getMemory(fragmentName, 展开深度, true);
`
$3
`typescript
await manager.setMemory(fragmentName, 内容);
`
$3
`typescript
await manager.deleteMemory(fragmentName);
`
$3
`typescript
await manager.renameMemory(旧文件名称, 新文件名称);
`
$3
`typescript
await manager.getMemoryHints(文件数量);
`
$3
`typescript
await manager.getOptimizeSuggestions(优化参数, 最大文件数量);
`
$3
`typescript
await manager.getIsolatedSuggestions(最大文件数量);
`
$3
`typescript
await manager.getSuggestions(优化参数, 最大文件数量);
`
🆕 v4.1 新功能详解
$3
当您在记忆片段中引用不存在的记忆片段时,系统会自动创建占位文件:
`typescript
// 创建包含引用的记忆片段
await manager.setMemory('学习计划', '今天要学习 [[JavaScript基础]] 和 [[React框架]]');
// 系统自动创建 JavaScript基础.md 和 React框架.md 占位文件
// 每个占位文件包含基础模板内容
`
$3
- 智能缓存: 权重计算结果被缓存,避免重复计算
- 自动失效: 文件修改时相关缓存自动清除
- 性能提升: 缓存命中时性能提升 60%+
$3
`
旧算法: 权重 = 引用数量
新算法: 权重 = 子记忆片段权重之和 + 引用数量
`
$3
`
旧公式: 价值 = 权重 / 字符数
新公式: 价值 = Sigmoid(权重) / 字符数
`
使用 Sigmoid 函数使权重影响更加平滑和科学。
安装
`bash
npm install modular-mcp-memory
`
使用示例
`typescript
import { ZettelkastenManager } from 'modular-mcp-memory';
// 创建管理器实例
const manager = new ZettelkastenManager({
storageDir: './my-cards',
autoCreateDir: true
});
// 创建记忆片段
await manager.setMemory('AI基础',
);
// 获取记忆片段内容(展开引用)
const content = await manager.getMemory('AI基础', 1);
// 获取智能提示
const hints = await manager.getMemoryHints(5);
console.log('推荐记忆片段:', hints.fragmentNames);
`
记忆片段引用语法
$3
使用 [[记忆片段名]] 引用其他记忆片段。
$3
记忆片段名称支持使用 / 来创建子目录结构:
`typescript
// 创建子目录中的记忆片段
await manager.setMemory('编程/JavaScript', 'JavaScript 相关内容');
await manager.setMemory('编程/前端/React', 'React 框架内容');
// 引用子目录中的记忆片段
await manager.setMemory('学习计划',
);
`
支持的子目录功能:
- ✅ 任意深度的子目录:category/subcategory/topic
- ✅ 跨目录引用:根目录记忆片段可以引用子目录记忆片段
- ✅ 自动创建目录:保存记忆片段时自动创建必要的目录结构
- ✅ 重命名支持:重命名子目录记忆片段会自动更新所有引用
注意事项:
- 记忆片段名不能以 / 开头
- 不支持相对路径操作(如 ../ 或 ./)
- 目录分隔符使用 /(会自动适配操作系统)
$3
使用 ![[记忆片段名]] 来展开引用记忆片段的内容。展开后的格式:
`markdown
![[记忆片段名]]start
记忆片段的实际内容
![[记忆片段名]]end
`
$3
从 v4.4.0 开始,系统使用新的内容展开标记格式:
`markdown
记忆片段的实际内容
`
优势:
- 更清晰的标记结构,避免与内容冲突
- 支持嵌套展开,不会相互干扰
- 更好的可读性和维护性
- 兼容 HTML 注释格式,在各种编辑器中都能正确显示
权重计算算法
系统使用递归算法计算记忆片段权重:
`typescript
// 当记忆片段有向外引用时
权重 = (引用记忆片段1权重 + 引用记忆片段2权重 + ... + 引用记忆片段n权重) / n
// 当记忆片段没有向外引用时
权重 = 1
`
价值计算
记忆片段价值用于优化建议:
`
价值 = 权重 / 字符数
`
价值越低的记忆片段可能需要优化(扩展内容或删除)。
信息散度
信息散度是衡量记忆片段价值的新指标,它鼓励信息的单元化和网络化:
`
信息散度 = 权重 / 字符数
`
与传统的价值计算相比,信息散度:
- 更注重信息的密度而非绝对价值
- 鼓励创建精简而高价值的记忆片段
- 促进记忆片段间的网络连接
- 避免过度冗长的内容积累
低信息散度的记忆片段通常表示:
- 内容过于冗长而信息密度低
- 缺乏足够的引用连接
- 可能需要精简或重新组织
系统片段
系统片段是具有特殊只读特性的记忆片段,用于存储系统核心配置和功能:
$3
- 只读特性: 系统片段不能被普通用户修改
- 自动识别: 系统自动识别并保护系统片段
- 核心功能: 用于存储系统级配置和功能
$3
系统片段通过内容前缀识别:
- 以 开头的记忆片段被识别为系统片段
- 系统片段会被自动排除在优化建议之外
- 系统片段的修改需要特殊权限或方法
$3
`markdown
系统配置
这是系统核心配置,不能被普通用户修改。
`
弃用说明
$3
getSuggestions 方法已被弃用,原因如下:
1. 算法不够精确: 使用 Sigmoid 函数计算价值,可能导致结果不够准确
2. 缺乏针对性: 无法区分低价值和孤立片段的不同优化需求
3. 性能问题: 计算复杂度较高,特别是在大型记忆库中
$3
建议使用以下两个专门的方法:
#### 1. getOptimizeSuggestions
专注于识别低价值的记忆片段:
- 使用信息散度计算,更加精确
- 专门针对内容密度低的片段
- 提供更准确的优化建议
#### 2. getIsolatedSuggestions
专注于识别孤立的记忆片段:
- 识别没有反向链接的片段
- 帮助发现记忆网络中的断点
- 促进记忆片段间的连接
$3
`typescript
// 旧方法(已弃用)
const suggestions = await manager.getSuggestions(0.1, 10);
// 新方法(推荐)
const lowValueSuggestions = await manager.getOptimizeSuggestions(0.1, 10);
const isolatedSuggestions = await manager.getIsolatedSuggestions(10);
`
开发
`bash
安装依赖
npm install
运行演示
npm run demo
运行测试
npm test
构建
npm run build
检查类型
npm run lint
`
API 文档
$3
#### 构造函数
`typescript
new ZettelkastenManager(config: ZettelkastenConfig)
`
#### 配置选项
`typescript
interface ZettelkastenConfig {
storageDir: string; // 存储目录路径
encoding?: string; // 文件编码,默认 'utf-8'
autoCreateDir?: boolean; // 是否自动创建目录,默认 true
}
`
#### 方法
- getMemory(fragmentName: string, expandDepth?: number, showLineNumbers?: boolean): Promise
- setMemory(fragmentName: string, content: string): Promise
- deleteMemory(fragmentName: string): Promise
- renameMemory(oldName: string, newName: string): Promise
- extractMemory(sourceFragmentName: string, targetFragmentName: string, range?: ExtractRange): Promise
- getMemoryHints(count: number): Promise
- getOptimizeSuggestions(optimizationParam: number, maxFileCount: number): Promise
- getIsolatedSuggestions(maxFileCount: number): Promise
- getSuggestions(threshold: number, maxCount: number): Promise (已弃用)
- getStats(): Promise
- getAllFragmentNames(): Promise
- insertLinkAt(sourceFragmentName: string, targetFragmentName: string, linePosition?: number, anchorText?: string): Promise
- getBacklinks(fragmentName: string): Promise
- clearCache(): void
许可证
MIT License
更新日志
$3
- 🆕 API重命名: 所有方法统一使用 fragmentName 参数名,方法名更语义化
- 🆕 新方法: 添加 getOptimizeSuggestions 方法,使用信息散度计算低价值片段
- 🆕 新方法: 添加 getIsolatedSuggestions 方法,识别孤立记忆片段
- 🆕 新展开格式: 引入新的内容展开标记格式 `