longterm-memory

LongtermMemory-MCP

一款完全本地运行的 MCP 服务，为 AI Agent 提供持久的语义长期记忆——无需依赖任何云服务。

灵感来自 mcp-mem0，但完全在你的设备上运行：

功能	mcp-mem0	本项目
存储	PostgreSQL / Supabase	SQLite（Node 内置的 node:sqlite）
嵌入	OpenAI API	本地 Transformer（all-MiniLM-L6-v2）
向量搜索	云端向量数据库	进程内余弦相似度
大模型依赖	OpenAI / OpenRouter / Ollama	无
安装	数据库 + API 密钥	npx longterm-memory-mcp

工具

核心工具

工具	说明
save_memory	存储文本，并自动生成语义嵌入、标签、重要性和类型
search_memory	使用自然语言查询查找相关记忆（余弦相似度）
update_memory	修改现有记忆的内容、元数据、标签、重要性或类型
delete_memory	根据 ID 删除指定记忆
delete_all_memories	清除所有记忆（不可撤销）
get_all_memories	列出所有已存储的记忆（分页）
memory_stats	获取数量和数据库位置

搜索

工具	说明
search_by_type	按类别筛选记忆（general、fact、preference、conversation、task、ephemeral）
search_by_tags	查找匹配任一所提供标签的记忆
search_by_date_range	查找在指定日期范围内创建的记忆（ISO 格式）

维护

工具	说明
create_backup	手动触发数据库备份并导出为 JSON

快速开始

Claude Code 插件（推荐）

通过 Claude Code 市场安装——这会同时配置 MCP 服务并安装配套技能，教会 Claude 如何有效使用记忆：

/plugin marketplace add MarcelRoozekrans/LongtermMemory-MCP
/plugin install longterm-memory@longterm-memory-marketplace

此操作会自动：

• 配置 MCP 服务（无需手动编辑 JSON）
• 安装 long-term-memory 技能（Claude 将学会在会话开始时回忆上下文、任务完成后保存见解，并对记忆去重）

使用 npx（无需安装）

npx longterm-memory-mcp

或全局安装

npm install -g longterm-memory-mcp
longterm-memory-mcp

或从源代码安装

git clone https://github.com/MarcelRoozekrans/LongtermMemory-MCP.git
cd LongtermMemory-MCP
npm install && npm run build
npm start

配置

Claude Code

如果你通过插件市场安装，MCP 服务已完成配置。手动配置时，请添加到 MCP 设置中（~/.claude/settings.json 或项目的 .claude/settings.json）：

{
  "mcpServers": {
    "longterm-memory": {
      "command": "npx",
      "args": ["-y", "longterm-memory-mcp"]
    }
  }
}

Claude Desktop

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "longterm-memory": {
      "command": "npx",
      "args": ["-y", "longterm-memory-mcp"]
    }
  }
}

Agent 指令

此代码库包含指导 AI Agent 有效使用记忆的指令（自动回忆、保存模式、去重）：

文件	用途
skills/long-term-memory/SKILL.md	独立技能——由 Claude Code 插件自动加载，也可供任何 MCP 客户端引用

数据库位置

默认情况下，记忆存储在共享的、按用户隔离的位置：

~/.longterm-memory-mcp/memories.db

这意味着每个项目和每个 MCP 客户端都共享同一个记忆池——你在一个项目中保存的记忆，在其他所有地方都可用。

多个会话可以同时使用同一个数据库。每个服务进程都会直接读取和写入共享文件（SQLite WAL 模式），因此在一个会话中保存的记忆会立即对其他所有会话可见，而且不会有会话覆盖其他会话保存的内容。需要 Node.js 22.13 或更高版本。

旧版本的数据库可以原样打开。对于没有 schema_meta 表的 v1.0–1.3 数据库，会原地迁移并保留其中的所有记忆；迁移前会在其旁边写入一个名为 memories.db.pre-migration-<timestamp>.bak 的副本。

从 1.4 或更早版本升级： 启动新版本之前，请停止所有使用旧版本的运行中会话。旧版本会将整个数据库保存在内存中，并在每次保存时重写文件，因此如果旧进程仍在运行，就会覆盖新会话保存的内容。

按项目使用数据库

若要为特定项目隔离记忆，请设置 MEMORY_DB_PATH 环境变量：

{
  "mcpServers": {
    "longterm-memory": {
      "command": "npx",
      "args": ["-y", "longterm-memory-mcp"],
      "env": {
        "MEMORY_DB_PATH": "/path/to/project/memories.db"
      }
    }
  }
}

记忆类型

每条记忆都有一个 memory_type，用于决定其分类方式和衰减速度：

类型	描述	衰减半衰期
general	默认通用类型	60 天
fact	已验证的信息	120 天
preference	用户／项目偏好	90 天
conversation	对话上下文	45 天
task	任务相关备注	30 天
ephemeral	短期上下文	10 天

标签与重要性

• 标签：使用字符串标签对记忆进行分类（例如 ["auth", "backend"]）。使用 search_by_tags 搜索。
• 重要性（1–10）：控制记忆抵抗衰减的能力。默认值为 5。重要性越高，衰减越慢。
• 受保护的标签：带有 core、identity 或 pinned 标签的记忆不会衰减。

衰减与强化

记忆会随时间衰减，以保持存储内容的相关性：

• 衰减：每种记忆类型都有一个半衰期（见上表）。重要性会根据上次访问以来的时间呈指数级下降，并设有下限以防止记忆被完全删除。
• 强化：每次通过搜索访问记忆时，其重要性都会增加 +0.1（最高为 10）。经常访问的记忆会保持较高的重要性。
• 惰性计算：在访问时计算衰减，而不是通过计时器计算——无需后台进程。

内容去重

保存时会对记忆内容进行哈希处理（SHA-256）。如果已有相同内容，保存操作会被拒绝，并返回对现有记忆 ID 的引用。这会自动防止重复条目。

备份

备份会自动管理，也可以通过 create_backup 工具手动触发。

• 自动备份：每 24 小时触发一次，或在记忆数量达到 100 的倍数时触发。
• 保留策略：保留最近 10 个备份；更早的备份会自动清理。
• 格式：每个备份都是一个带时间戳的目录，其中包含 SQLite 数据库的一致性快照，以及所有记忆的 JSON 导出文件。
• 位置：默认位于 ~/.longterm-memory-mcp/backups/，也可以设置 MEMORY_BACKUP_PATH：

{
  "mcpServers": {
    "longterm-memory": {
      "command": "npx",
      "args": ["-y", "longterm-memory-mcp"],
      "env": {
        "MEMORY_BACKUP_PATH": "/path/to/backups"
      }
    }
  }
}

工作原理

1. 保存：使用 all-MiniLM-L6-v2 在本地为文本生成嵌入（384 维向量），并将其与原始内容、元数据、标签、重要性和类型一同存储在 SQLite 中。内容通过 SHA-256 哈希去重。
2. 搜索：使用相同的模型为查询生成嵌入，然后通过余弦相似度将其与每条已存储记忆进行比较。高于阈值的结果会按相关性排序后返回。被访问的记忆会自动强化。
3. 衰减：随着时间推移，未使用的记忆会根据其类型的半衰期降低重要性。受保护且频繁访问的记忆不易衰减。
4. 持久化：每次更改都会直接写入磁盘上的 SQLite 数据库，因此并发会话共用同一个一致的数据存储。无需后台进程，也无需维护服务。

嵌入模型（量化后约 30MB）会在首次使用时下载一次，并缓存在本地。

架构

src/                           — MCP server source
  index.ts                     — Entry point (stdio transport, DB/backup path resolution)
  server.ts                    — MCP server factory + 11 tool definitions
  memory-store.ts              — SQLite storage + vector search + decay integration
  embeddings.ts                — Local embedding engine (Xenova/transformers)
  decay.ts                     — DecayEngine (lazy decay, reinforcement, protected tags)
  backup.ts                    — BackupManager (auto-backup, JSON export, pruning)
  types.ts                     — TypeScript interfaces (Memory, Embedder, config types)

skills/                        — Claude Code plugin skill
  long-term-memory/SKILL.md    — Self-contained agent instructions + skill

.claude-plugin/                — Plugin & marketplace metadata
  plugin.json                  — Plugin manifest
  marketplace.json             — Marketplace manifest
.mcp.json                      — Auto-configures MCP server on plugin install
.vscode/mcp.json               — VS Code MCP server config

基准测试

运行 npm run bench。以下结果来自使用模拟嵌入的内存存储（将存储和 SQLite 的性能与模型延迟隔离）：

余弦相似度

操作	吞吐量	说明
单次计算（384 维）	~4.2M ops/s	与实际嵌入维度一致
128 维	~8.6M ops/s
768 维	~2.4M ops/s
1536 维	~1.3M ops/s	随维度线性扩展

记忆存储操作

操作	吞吐量	说明
保存（单条）	~1,120 ops/s	包含嵌入生成、SQLite 插入和去重检查
保存 100 条批次	~18 ops/s	每批 100 条约需 55ms
保存 1000 条批次	~0.3 ops/s	每批 1000 条约需 3.1s
更新（内容，重新生成嵌入）	~155 ops/s
更新（仅元数据）	~344 ops/s	比更新内容快 2.2 倍
删除	~469 ops/s

搜索（语义搜索，规模测试）

存储大小	操作	说明
10 条记忆	search (limit=5)	全量扫描，并对每条记忆计算余弦相似度
100 条记忆	search (limit=5)
500 条记忆	search (limit=5)
1000 条记忆	search (limit=5)	线性扫描——随存储大小扩展

衰减引擎

操作	吞吐量
单次衰减计算	~21M ops/s
单次强化	~25.7M ops/s
shouldProtect（标签检查）	~22M ops/s

开发

npm install          # Install dependencies
npm run build        # Compile TypeScript
npm test             # Run all tests
npm run bench        # Run benchmarks
npm run test:watch   # Watch mode
npm run test:coverage # Coverage report

贡献

本项目使用 Conventional Commits 和 semantic-release 自动管理版本。

提交消息格式

<type>(<optional scope>): <description>

[optional body]

[optional footer(s)]

类型	用途	版本变更
feat	新功能	次版本（0.x.0）
fix	修复错误	补丁版本（0.0.x）
docs	仅文档变更	不发布
style	格式、空白字符	不发布
refactor	代码重构	不发布
test	添加或更新测试	不发布
chore	维护、依赖项	不发布
ci	CI/CD 变更	不发布

重大变更：在类型后添加 !（例如 feat!: remove deprecated API），或添加 BREAKING CHANGE: 页脚。这会触发主版本升级。

示例

git commit -m "feat: add memory tagging support"
git commit -m "fix: handle empty search query gracefully"
git commit -m "feat!: change default database location"
git commit -m "docs: update configuration examples"

提交消息通过 commitlint 和 husky Git 钩子在本地验证。不符合规范的消息将被拒绝。

发布

发布流程完全自动化。将提交推送到 main 后：

1. semantic-release 分析提交消息
2. 确定下一个版本（主版本 / 次版本 / 补丁版本）
3. 根据提交生成发布说明
4. 更新 CHANGELOG.md
5. 发布到 npm
6. 创建 GitHub Release

无需手动升级版本或创建标签。

依赖项更新

依赖项由 Renovate 自动管理。CI 通过后，补丁和次版本的开发依赖项更新会自动合并。主版本更新则会创建 PR 以供人工审核。

许可证

MIT