使用说明
本地存储器mcp
为AI助手提供持久、可搜索的内存。使用混合搜索将对话、决策和偏好存储在纯Markdown中。专为代理工作流程而设计。
结合BM25关键字搜索和矢量语义搜索 互易秩融合（RRF） 拥有顶级奖金——所有奖金都通过transformers.js在本地运行。
快速开始
# Install and build
pnpm install
pnpm run build
# Set environment variable (add to ~/.zshrc or ~/.bashrc)
export LOCAL_MEMORY_MCP="/path/to/memory-mcp-node"
MCP客户端配置：
{
"memory": {
"command": "bash",
"args": ["-c", "node \"$LOCAL_MEMORY_MCP/dist/index.js\""]
}
}
代理说明
添加 MEMORY_PROTOCOL_RULE.md 致您的编码代理：
| 代理 | 位置 |
|---|---|
| 游标 | 用户规则或项目 .cursorrules |
| 克劳德代码 | ~/.claude/CLAUDE.md |
| 食品法典委员会 | ~/.codex/AGENTS.md |
建筑
┌─────────────────────────────────────────────────────────────────────────────┐
│ local-memory-mcp Hybrid Search Pipeline │
└─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────┐
│ User Query │
└────────┬────────┘
│
┌──────────────┴──────────────┐
▼ ▼
┌────────────────┐ ┌────────────────┐
│ Vector Search │ │ BM25 Search │
│ (semantic) │ │ (keywords) │
└───────┬────────┘ └───────┬────────┘
│ │
│ Ranked List │ Ranked List
│ │
└──────────────┬──────────────┘
│
┌───────────────────────┐
│ RRF Fusion (k=60) │
│ score = Σ 1/(k+rank) │
└───────────┬───────────┘
│
┌───────────────────────┐
│ Top-Rank Bonus │
│ #1 in either: +0.05 │
│ #1 in both: +0.10 │
└───────────┬───────────┘
│
┌───────────────────────┐
│ Deduplication │
│ 70% Jaccard threshold│
└───────────────────────┘
分数融合策略
| 后端 | 原始分数 | RRF贡献 |
|---|---|---|
| 矢量 | 余弦相似性 | 1 / (60 + rank) |
| BM25 | SQLite FTS5 | 1 / (60 + rank) |
为什么选择RRF？ 加权混合(0.7×vector + 0.3×bm25)产生了泥泞的中间地带，正确的结果几乎无法与噪声区分开来。带有顶级奖金的RRF会造成决定性的信心差距：
| 查询 | 旧差距 | 新差距 |
|---|---|---|
| 精确匹配 | 2.0× | 8.2× |
| 模糊匹配 | 1.0× | 4.1× |
存储结构
~/.memory-mcp/
├── MEMORY.md # Long-term memories (source of truth)
├── index.sqlite # Search index (vector + FTS5 + metadata)
└── memory/
├── 2025-01-28.md # Daily conversation files
└── 2025-01-29.md
数据流
写(memory_store):
Text ──► Chunk (400 tokens) ──► Embed (384d) ──► Store in:
├─ Markdown file
├─ Vector index (sqlite-vec)
└─ Keyword index (FTS5)
阅读(memory_search):
Query ──► Embed ──► [Vector Search] ─┬─► RRF Fusion ──► Top-Rank Bonus ──► Results
[BM25 Search] ──┘
MCP工具
| 工具 | 目的 |
|---|---|
memory_search |
混合搜索（矢量+BM25+RRF） |
memory_store |
保存新信息 |
memory_list_recent |
加载最近上下文（过去N天） |
memory_get |
按路径读取特定文件 |
memory_forget |
删除记忆（带预览） |
memory_status |
检查系统运行状况 |
技术栈
| 技术 | 目的 |
|---|---|
| 变压器.js | 本地嵌入（384d，离线） |
| SQLite+ sqlite-vc | 矢量+关键字索引 |
| Markdown文件 | 人类可读存储 |
| 拟人克劳德 | 仅维护（可选） |
维护（可选）
单独的CLI工具用于自动清理和事实提取。需要 ANTHROPIC_API_KEY.
# Check status
node dist/maintenance.js --action check
# Run full maintenance
node dist/maintenance.js --action full --dry-run false
| 行动 | 它的作用 |
|---|---|
retention |
删除旧的日常文件 |
compaction |
在日常文件中进行重复数据消除 |
promotion |
将重要事实提取到MEMORY.md |
cleanup |
消除噪音，重新索引 |
full |
以最佳顺序运行 |
成本： 每次完整运行约0.05-0.25美元，每天定时约1.50-7.50美元/月。
日程
node dist/maintenance.js schedule
创建/查看/删除每日cron作业的交互式菜单（09:00 UTC）。
配置
API密钥 (~/.memory-mcp/.env):
# Optional - only needed for maintenance
ANTHROPIC_API_KEY=sk-ant-...
设置 (config.json):
{
"memoryDir": "/Users/you/.memory-mcp",
"maintenance": {
"compactionThresholdKB": 50,
"promotionScoreThreshold": 0.8
}
}
发展
pnpm install
pnpm run build
pnpm run dev # watch mode
pnpm run test # 51 tests
关键模块
| 模块 | 目的 |
|---|---|
src/core/search.ts |
RRF混合搜索 |
src/core/database.ts |
SQLite+SQLite-vec |
src/core/indexer.ts |
分块+嵌入 |
src/core/maintenance.ts |
清理编排 |
需求
- Node.js 18+
- pnpm（或npm）
- 无烟煤API键（可选，用于维护）
许可证
麻省理工学院
