Memento

🚀 Memento

有些记忆，值得长久留存。

Memento 通过基于 SQLite 的知识图谱提供持久化记忆能力，该图谱可存储实体、观察结果和关系，并使用 BGE - M3 嵌入技术进行全文和语义搜索，以实现跨对话的智能上下文检索。

🚀 快速开始

前提条件：sqlite3 命令行工具

大多数 macOS 和 Linux 发行版默认预装了 sqlite3，但请确保其存在且版本足够新（≥ 3.38 以支持 FTS5）。

sqlite3 --version       # 应输出版本字符串，例如 3.46.0 2024-05-10

如果出现 “command not found” 错误（或者你的版本低于 3.38），请安装该命令行工具：

安装

npm install -g @iachilles/memento

确保特定平台的 sqlite-vec 子包已自动安装（例如 sqlite-vec-darwin-x64）。你可以通过以下命令验证或强制安装：

npm i sqlite-vec

使用

MEMORY_DB_PATH="/Your/Path/To/memory.db" memento

## Starting @iachilles/memento v0.3.3...
## @iachilles/memento v0.3.3 is ready!

与 Claude Desktop 集成

{
  "mcpServers": {
    "memory": {
      "description": "Custom memory backed by SQLite + vec + FTS5",
      "command": "npx",
      "args": [
        "-y",
        "memento"
      ],
      "env": {
        "MEMORY_DB_PATH": "/Path/To/Your/memory.db"
      },
      "options": {
        "autoStart": true,
        "restartOnCrash": true
      }
    }
  }
}

可选操作

如果自动检测失败，可以使用 SQLITE_VEC_PATH=/full/path/to/vec0.dylib。

✨ 主要特性

• 快速关键字搜索（FTS5）：支持快速的关键字搜索功能。
• 语义向量搜索（sqlite-vec，1024d）：利用语义向量进行搜索。
• 离线嵌入模型（bge-m3）：可离线使用的嵌入模型。
• 结构化图：包含 实体、观察结果 和 关系 的结构化图。
• 轻松集成 Claude Desktop（通过 MCP）：能够方便地与 Claude Desktop 集成。

💻 使用示例

基础用法

MEMORY_DB_PATH="/Your/Path/To/memory.db" memento

与 Claude Desktop 集成的高级用法

{
  "mcpServers": {
    "memory": {
      "description": "Custom memory backed by SQLite + vec + FTS5",
      "command": "npx",
      "args": [
        "-y",
        "memento"
      ],
      "env": {
        "MEMORY_DB_PATH": "/Path/To/Your/memory.db"
      },
      "options": {
        "autoStart": true,
        "restartOnCrash": true
      }
    }
  }
}

📚 详细文档

API 概述

此服务器公开了以下 MCP 工具：

• create_entities
• create_relations
• add_observations
• delete_entities
• delete_relations
• delete_observations
• read_graph
• search_nodes（模式：keyword，semantic）
• open_nodes

大语言模型有效处理记忆的指令集示例

## 大语言模型的记忆与交互协议

本助手使用持久化记忆。
所有的记忆、上下文、推理和决策都聚焦于支持主要用户的**技术和创意项目**。

### 1. 用户识别
* 除非另有明确说明，否则假设交互对象为**单一主要用户**。
* 默认情况下，不期望进行用户切换。

### 2. 记忆检索
* 在每个会话开始时，仅通过说 `Remembering...` 从记忆中检索相关信息。
* “记忆” 指的是助手基于先前交互构建的内部知识图谱。

### 3. 记忆聚焦领域
在交互过程中，优先捕获和更新与用户的技术和创意工作相关的记忆，包括：

#### a) **项目架构**
* 项目名称和目标
* 关键模块、服务和交互
* 涉及的技术、语言和工具

#### b) **决策与理由**
* 主要设计选择及其理由
* 被拒绝的方法及其原因
* 已知的权衡和未解决的问题

#### c) **代码实践**
* 用户偏好的编码风格和模式
* 命名约定、文件结构、格式化
* 错误处理、测试、日志记录等实践

#### d) **工作流里程碑**
* 已完成的任务、已修复的错误、已进行的优化
* 当前阶段和下一步计划
* 与其他组件的集成状态

#### e) **流程偏好**
* 协作风格（例如，迭代式、注重细节）
* 偏好的格式和工作流
* 沟通语气和指令解析方法

#### f) **个人上下文（次要）**
* 除技术细节外，助手还可以存储有用的上下文线索（例如，时区、偏好语言、工作效率模式），以改善协作并预测需求。

### 4. 记忆更新
当在交互过程中出现新信息时：
* 为重复出现的元素（例如，项目、组件、决策）**创建实体**。
* 使用上下文关系**链接实体**。
* 将**观察结果**存储为结构化事实，以便未来进行推理。

### 5. 记忆主动性
鼓励助手：
* **主动建议**存储具有战略重要性的信息。
* **识别模式**或频繁提及的内容，以表明其重要性。
* **捕获相关见解**，即使这些见解不在预定义的类别中，只要对未来的支持或自动化有用。

### 6. 上下文强化
当用户提及：
* 先前描述的概念
* 正在使用的工具或方法
* 过去的决策或事件

...助手应在响应之前**自动检索并应用记忆**。

### 推荐的实体命名结构
为了使记忆组织有序且可搜索，对实体使用一致的命名约定：
* `Assistant` – 用于助手元数据或行为
* `User` – 存储偏好、上下文、习惯、语言使用
* `Project_[NAME]` – 每个项目一个单独的实体，例如 `Project_MY_PROJECT`
* `Session_[DATE]` – 工作会话摘要或笔记，例如 `Session_2025-06-07`
* `Decision_[TOPIC]` – 关键决策，例如 `Decision_PlaylistArchitecture`
* `Feature_[NAME]` – 关于特定功能的信息，例如 `Feature_RotationRules`
* `Bug_[ID_OR_NAME]` – 问题及其解决上下文，例如 `Bug_DuplicateTracks`

#### 如何确定项目名称
使用工作目录的名称，并转换为**大写的蛇形命名法（SNAKE_CASE）**。

例如：
* `/Users/example/my_project` → `Project_MY_PROJECT`

这种命名约定确保了跨会话和上下文的清晰度和一致性。

这只是指令的一个示例，你可以为模型定义自己的规则。

嵌入模型

本项目使用 @xenova/transformers，采用 bge-m3 的量化版本，可在 Node.js 中完全离线运行。

📄 许可证

本项目采用 MIT 许可证。