Memento

Memento

有些记忆值得持久保存。

通过基于 SQLite 的知识图谱提供持久记忆功能，存储实体、观察结果和关系，并使用 BGE-M3 嵌入进行语义搜索，以便在不同对话中智能检索上下文。

功能

• 语义向量搜索（sqlite-vec/pgvector，1024d）
• 离线嵌入模型（bge-m3）
• 支持 SQLite 和 PostgreSQL 后端的模块化存储库层
• 增强相关性评分，综合考虑时间、热度、上下文和重要性因素
• 由 entities、observations 和 relations 构成的结构化图谱
• 轻松集成 Claude Desktop（通过 MCP）

前置条件

系统 SQLite 版本检查

Memento 需要 SQLite 3.38+。大多数 macOS 和 Linux 发行版都预装了 sqlite3，但请再次确认它已安装且版本足够新：

sqlite3 --version       # should print a version string, e.g. 3.46.0

重要说明： 此检查仅用于确认系统中已安装 SQLite。Memento 的运行不使用 sqlite3 CLI，而是在内部使用 Node.js sqlite3 模块。

如果看到“command not found”（或版本低于 3.38），请安装 SQLite：

平台	安装命令
macOS（Homebrew）	brew install sqlite
Debian / Ubuntu	sudo apt update && sudo apt install sqlite3

配置

Memento 现在支持可插拔的存储后端。配置完全通过环境变量控制， 因此可以轻松嵌入 MCP 工作流。

变量	说明
MEMORY_DB_DRIVER	可选的数据库后端选择器。默认为 sqlite。设为 postgres 可启用 PostgreSQL 管理器。
MEMORY_DB_PATH	SQLite 数据库文件的文件系统路径（仅当驱动为 sqlite 时使用）。
SQLITE_VEC_PATH	可选的预构建 sqlite-vec 扩展共享库的绝对路径。
MEMORY_DB_DSN / DATABASE_URL	由 pg 客户端使用的 PostgreSQL 连接字符串。
PGHOST、PGPORT、PGUSER、PGPASSWORD、PGDATABASE	PostgreSQL 的独立连接参数。未提供 DSN 时使用。
PGSSLMODE	设为 require 时，将启用 SSL，并设置 rejectUnauthorized: false。
MEMENTO_WRITE_HOOK_PATH	可选的 JSON Lines 文件路径。设置后，每次图谱变更成功后，Memento 都会追加一条事件。

写入钩子事件

如果其他进程需要在记忆写入时作出响应，而不轮询整个图谱，请设置 MEMENTO_WRITE_HOOK_PATH：

MEMENTO_WRITE_HOOK_PATH=/tmp/memento-events.jsonl memento

每行都是一个 JSON 对象，包含 ISO 格式的 timestamp、一个 operation，以及变更后的实体/关系负载。示例：

{"timestamp":"2026-05-05T16:33:16.619Z","operation":"create_entity","entity":{"name":"Hook Test","entityType":"test"}}

支持的操作包括 create_entity、add_observations、create_relation、delete_entities、delete_relations、delete_observations 和 set_importance。仅当记录实际被删除时才会发出删除事件。

钩子写入失败会记录到 stderr，但不会导致已成功的图谱变更失败。需要严格对账的使用方应将钩子与定期调用 read_graph 或针对性调用 open_nodes 检查结合使用。

PostgreSQL 说明

• PostgreSQL 管理器需要 pgvector 扩展。系统会自动通过 CREATE EXTENSION IF NOT EXISTS vector 进行初始化。

Claude Desktop：

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

故障排除

sqlite-vec 扩展问题

重要提示： Memento 通过 Node.js 以编程方式加载 sqlite-vec 扩展，而不是通过 sqlite3 CLI 加载。

常见误解：

• ❌ 为 sqlite3 CLI 创建 shell 别名不会影响 Memento
• ❌ 在 sqlite3 CLI 中加载扩展对 Memento 没有帮助
• ✅ 使用通过 npm 安装的 sqlite-vec；如果自动检测失败，则设置 SQLITE_VEC_PATH 环境变量。该变量应指向与 Node.js 兼容的扩展版本，通常位于 node_modules 目录中。

如果自动加载 vec 失败：

# Find the Node.js-compatible vec extension
find node_modules -name "vec0.dylib"  # macOS
find node_modules -name "vec0.so"     # Linux

# Use it via environment variable
SQLITE_VEC_PATH="/full/path/to/node_modules/sqlite-vec-darwin-x64/vec0.dylib" memento

API 概览

此服务提供以下 MCP 工具：

• create_entities
• create_relations
• add_observations
• delete_entities
• delete_relations
• delete_observations
• read_graph
• search_nodes
• open_nodes
• set_importance - 设置重要性级别（critical/important/normal/temporary/deprecated）

配置 MEMENTO_WRITE_HOOK_PATH 后，修改数据的工具还会追加 JSONL 写入事件，供下游使用者使用。

LLM 应了解的一套用于有效管理记忆的指令示例（参见 MEMORY_PROTOCOL.md）

嵌入模型

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

许可证

MIT