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 許可證。