Memento

面向本地优先、与大模型无关的 AI 助手记忆层
runmemento.com

每次 AI 会话开始时，情况都一样：你得重新解释自己的偏好、项目约定、上周做出的决定，以及应该避开的死胡同。每种工具都用各自封闭的方式解决这个问题（CLAUDE.md、.cursorrules、copilot-instructions.md、ChatGPT Memory）——但始终不变的是你这个人。你的记忆不该分散在不同供应商那里。

Memento 为这些记忆提供了统一的存放位置。它通过本地 SQLite 文件运行一个 MCP 服务，因此任何支持 MCP 的 AI 助手——Claude Desktop、Claude Code、Cursor、GitHub Copilot、Cline、OpenCode、Aider、研究机器人或自定义 Agent——都能读取和写入关于你、你的工作和你所做决定的持久化结构化记忆。以本地为先，默认不进行出站网络调用，也不会被供应商锁定。

_{全新的聊天没有任何先前上下文——Memento 提供上周所做决定的记忆。}

快速入门

只需三步，即可从零开始搭建可用的记忆层：

1. 运行 init（在 TTY 中交互式运行）

npx @psraghuveer/memento init

在 XDG 默认目录下创建数据库（$XDG_DATA_HOME/memento/memento.db，在 POSIX 系统上通常为 ~/.local/share/memento/memento.db），运行迁移，并在 TTY 中引导你完成四个只需按一次按键的设置问题：

• 你偏好的称呼。 作为 user.preferredName 配置项存储，这样记忆会显示为“Raghu 偏好……”而不是“用户偏好……”。
• 安装随附的技能？ 输入 y/N 即可。将 skills/memento/ 复制到 ~/.claude/skills/，供加载 Anthropic 格式技能的客户端使用。
• 使用入门包初始化？ 从四个随附包（engineering-simplicity、pragmatic-programmer、twelve-factor-app、google-sre）中选择一个，让记忆库从第一天起就有实用内容。也可以跳过，从空库开始。
• 自动安装 persona 片段？ 检测你机器上的 AI 客户端，并将带标记的代码块写入各客户端用户级别的自定义指令文件（Claude Code 的 ~/.claude/CLAUDE.md、OpenCode 的 ~/.config/opencode/AGENTS.md、Cline 的 ~/Documents/Cline/Rules/memento.md）。此操作可幂等重复执行，也可移除。仅支持 UI 操作的客户端（Cowork、Claude Desktop、Claude Chat、Cursor User Rules）则会显示可复制粘贴的说明。

随后会为每个受支持的客户端打印可直接复制粘贴的 MCP 配置片段。此操作可幂等重复执行——随时重新运行，即可再次打印配置片段，并重新询问之前跳过的问题。传入 --no-prompt 可跳过交互流程（适用于 CI、脚本）。

2. 连接你的 AI 客户端

init 会输出一行子命令（客户端内置了子命令时），或一段 JSON 片段，供你合并到客户端的 MCP 配置中。选择适用于你客户端的内容，粘贴后，重启客户端，以便加载新的 MCP 服务。

各客户端的完整操作指南见 docs/guides/mcp-client-setup.md。

3. 确认人格片段已传递给你的助手

Memento 提供三种指导方式——通过网络传递的 MCP instructions 主干、面向支持技能的客户端的内置技能，以及人格片段。三者之中，只有人格片段能保证在每条消息中都进入助手的系统提示词——MCP 规范允许不提供 instructions，而不同客户端对是否展示它的实现也不尽相同；技能由意图触发，因此不会在中性的首条消息中触发。

如果你在第 1 步的人格自动安装提示中选择了 Y，那么已为检测到的所有基于文件的 AI 客户端完成安装——相应片段已写入 ~/.claude/CLAUDE.md、~/.config/opencode/AGENTS.md 和／或 ~/Documents/Cline/Rules/memento.md（视情况而定）。对于仅支持 UI 的客户端（Cowork、Claude Desktop、Claude Chat（位于 claude.ai）、Cursor User Rules），以及自动安装程序未触发的任何客户端，请从 docs/guides/teach-your-assistant.md 复制人格片段，并粘贴到客户端的自定义指令／系统提示词栏位中（栏位名称因客户端而异，例如客户端设置 UI 中的“自定义指令”等）。

就是这样。使用 npx @psraghuveer/memento verify-setup 验证整个调用链路是否正常——该命令会执行写入／搜索／清理往返流程，证明你的助手确实可以调用 Memento。

接着试试开启一个新会话：“记住，对于 Node 项目，我更喜欢 pnpm 而不是 npm。” 在下一次会话中，询问 “我偏好的包管理器是什么？”，助手应该能回想起来，无需你再次解释。

用资源包填充你的存储

全新安装的 Memento 是空的。资源包是经过整理的 YAML 记忆合集，可通过一步安装——例如技术栈指南（Rust + Axum、TypeScript + pnpm、Python + uv……）、团队约定，或你在另一台机器上编写的个人合集。

memento pack install engineering-simplicity

此命令会安装一个内置资源包，其中包含从 John Maeda 的 The Laws of Simplicity 提炼出的 11 条记忆。开箱即附带四个资源包：engineering-simplicity、pragmatic-programmer（Hunt 和 Thomas 的技巧）、twelve-factor-app（Wiggins / Heroku）和 google-sre（Google 的 SRE 书籍）。安装前可使用 memento pack preview <id-or-path> 预览；使用 memento pack list 查看已安装内容；随时使用 memento pack uninstall <id> --confirm 移除（默认先执行试运行）。

资源包也是分享内容的方式。使用 memento pack create 从现有记忆创建资源包，然后将其作为文件、HTTPS URL 或社区贡献进行分发。保留的 pack:<id>:<version> 标签会标记每条通过资源包安装的记忆，确保来源信息始终不变。完整指南：docs/guides/packs.md。设计依据：ADR-0020。

入门

前置条件。 Node.js ≥ 22.11，以及 C/C++ 工具链，以便在没有预构建版本的平台上编译 better-sqlite3（macOS 上的 Xcode 命令行工具，Debian/Ubuntu 上的 build-essential）。

运行一次 init 完成设置：

npx @psraghuveer/memento init

init 默认将数据库放在 XDG 数据目录中；如果要使用非默认位置，请传入 --db /custom/path/memento.db（或设置 MEMENTO_DB=/custom/path/memento.db）。

要直接运行服务（例如用于调试）：

npx @psraghuveer/memento serve

该服务通过 stdio 监听 MCP 请求。要传入额外标志（例如自定义数据库位置）：

npx @psraghuveer/memento serve --db ~/.local/share/memento/memento.db

你也可以使用 MEMENTO_DB 环境变量指定一个现有数据库。

验证安装：运行 npx @psraghuveer/memento doctor（添加 --quick 可跳过数据库和嵌入器探测；添加 --mcp 还会扫描已知的 MCP 客户端配置文件）。要用一个屏幕查看存储中的内容摘要，请运行 npx @psraghuveer/memento status。要在不通过 MCP 通信的情况下检查安装可执行的操作——已注册的命令、当前配置、数据库位置——请运行 npx @psraghuveer/memento context。要端到端冒烟测试 MCP 传输，请运行 npx @psraghuveer/memento ping。

将 Memento 接入 MCP 客户端（Claude Desktop、Claude Code、Cursor、Cline、OpenCode、VS Code Agent 模式等）的逐步说明见 docs/guides/mcp-client-setup.md。简而言之，快速入门分为上述三个步骤：运行 init（如果你回答 Y，它会自动将 persona 片段安装到检测到的文件型客户端中），将 MCP 服务片段粘贴到客户端，然后对于仅提供 UI 的客户端，手动粘贴 persona 片段。

向量检索（基于 FTS 的释义匹配）默认启用。首次搜索会触发一次性模型下载（约 110 MB），并将模型保存到 $XDG_CACHE_HOME/memento/models（或 ~/.cache/memento/models / %LOCALAPPDATA%\memento\Cache\models）；之后，FTS 和向量检索分支都会自动运行。如果模型尚未下载，搜索会平稳降级为仅使用 FTS。配置选项和库接入详情见 docs/guides/embeddings.md。

日常管理存储——compact、backup、status、定时安排——请参阅 docs/guides/operations.md。冲突处理工作流见 docs/guides/conflicts.md。要帮助 AI 助手掌握如何有效使用 Memento，请参阅 docs/guides/teach-your-assistant.md；如果你的客户端会加载 Anthropic 格式的技能，还可以安装随附的 技能，在触发意图时作为 persona 片段的补充。

在浏览器中查看和整理存储。 npx @psraghuveer/memento dashboard 会启动一个本地优先的 Web UI，读取你的 MEMENTO_DB：按类型和范围统计记忆数量、审计跟踪、冲突分流、配置检查、已安装套件。仅限 localhost 访问，通过启动器传给浏览器的 URL 中每次启动随机生成的令牌进行保护，不收集遥测数据。仪表板是一个同级软件包（@psraghuveer/memento-dashboard），依据 ADR-0018 发布；完整操作指南见 docs/guides/dashboard.md。

遇到问题？ 常见故障（better-sqlite3 构建错误、command not found: memento、STORAGE_ERROR、缺少嵌入器依赖）请参阅 docs/guides/troubleshooting.md。

贡献者工作流（分支、提交约定、PR 检查清单）请参阅 CONTRIBUTING.md。在代码库上工作的 AI Agent 必须阅读 AGENTS.md。

指导原则

所有设计决策都依据以下四项原则进行评判。详见 ARCHITECTURE.md。

1. 第一性原理。 每个构造都源于我们已证实的需求，而不是因为惯例如此。
2. 模块化。 替换任何组件都不必重写其余部分。
3. 可扩展。 新变体无需引入破坏性变更。
4. 由用户配置驱动。 行为由配置决定，而不是由代码决定。

Memento 是什么

四大支柱。其他地方也始终用这四个词来描述它。

• 本地。 主目录下的一个 SQLite 文件。默认不使用云服务、不收集遥测数据，也不进行任何出站网络调用。完全离线。
• 类型化。 五种记忆类型——fact、preference、decision、todo、snippet——各自带有专属字段（decision 会记录其理由，todo 会记录其截止日期，snippet 会记录其语言）。助手可以推理哪些内容仍然有效，而不只是检索文本块。
• 可审计。 每次写入都会在只追加日志中生成一条事件。冲突会显现出来以供分流处理，而不是悄然共存。如果你不确认记忆，它们会逐渐衰减。你可以随时询问“为什么要记录这条？”以及“它何时发生了变化？”
• 归你所有。 行为可配置（每个检索权重、每个衰减半衰期、每条清理规则），支持 JSONL 导出和导入，采用 Apache-2.0 许可证。你可以在不同机器间携带自己的记忆，随时离开，不受供应商锁定。

此外：与大模型无关（适用于客户端所使用的任何模型），原生支持 MCP（Claude Desktop、Claude Code、Cursor、GitHub Copilot、Cline、OpenCode、Aider、自定义 Agent），注重隐私（正则清理器会在持久化之前剔除机密信息；匹配模式由用户配置）。

Memento 不是什么

• 不是聊天历史存储库。它记录的是提炼后的结构化记忆——偏好、事实、经历、经验——而不是原始对话记录。
• 不是知识图谱或语义数据库。这类用途请使用合适的工具。
• 不是云服务。记忆保存在你的机器上；云端嵌入、跨机器同步和团队共享记忆均不属于本产品的范畴。
• 不是插件平台。架构为未来保留了空间，但 Memento 目前提供固定的功能范围，以确保质量。

完整的范围外事项和当前限制列表见 KNOWN_LIMITATIONS.md。

各部分如何协同工作

┌─────────────────────────────────────────────────────────┐
│  Clients: Claude Desktop, Claude Code, Cursor, Copilot, │
│           OpenCode, custom agents, …                    │
└──────────────────────┬──────────────────────────────────┘
                       │ MCP (stdio)
┌──────────────────────▼──────────────────────────────────┐
│  memento-server (MCP adapter)                           │
└──────────────────────┬──────────────────────────────────┘
                       │ Command registry
┌──────────────────────▼──────────────────────────────────┐
│  memento-core: services, scope resolver, scrubber,      │
│                conflict detector, decay engine          │
└──────────────────────┬──────────────────────────────────┘
                       │ Repository interfaces
┌──────────────────────▼──────────────────────────────────┐
│  SQLite (better-sqlite3) + FTS5 + optional sqlite-vec   │
└─────────────────────────────────────────────────────────┘

完整的架构说明见 ARCHITECTURE.md。每项重要决策都有一份 架构决策记录。

面向贡献者（人类或 AI）

欢迎人类作者和 AI 辅助作者提交贡献。我们对两者采用相同的标准。

• 如果你是 AI Agent 或正在与 AI Agent 协作，请阅读 AGENTS.md。 这是规范的指令集；CLAUDE.md 和 .github/copilot-instructions.md 是指向它的简要文件。
• 有关开发环境设置、分支管理、提交约定和 PR 生命周期，请阅读 CONTRIBUTING.md。
• 进行任何实质性更改前，请先创建一个设计提案议题。
• 请使用 PR 模板。 模板要求你说明更改的理由，而不只是描述更改内容。

我们使用 GitHub Discussions 交流问题和想法；议题跟踪器用于报告错误和跟踪已接受的工作。

许可证

Apache-2.0。版权归属信息见 NOTICE。

软件包

Memento 是一个由专注于特定功能的软件包组成的小型工作区。架构记录在 docs/architecture/ 中，设计决策记录在 docs/adr/ 中；两者都是了解 Memento 的功能及其设计缘由的权威来源。

软件包	说明
@psraghuveer/memento-schema	记忆 / 事件 / 作用域 / 清理器 / 冲突 / 配置 / 结果架构，以及针对每个 ConfigKey 的值架构。
@psraghuveer/memento-core	存储和迁移、记忆与事件存储库、作用域解析器、清理器、带有 compact 归档阶段的衰减引擎、冲突检测与取代工作流、嵌入钩子与批量重新嵌入驱动程序、EmbeddingProvider 接口、FTS + 暴力向量检索流水线 + 排序器，以及带验证执行路径的命令注册表（ADR 0003）。
@psraghuveer/memento-server	MCP 适配器——buildMementoServer 将 @psraghuveer/memento-core 命令注册表映射为 MCP 工具；serveStdio 将其连接到标准输入输出。由 memento serve 使用。
@psraghuveer/memento-embedder-local	基于 transformers.js + bge-base-en-v1.5 的本地 EmbeddingProvider。作为常规依赖提供；首次使用时，惰性的 single-flight 初始化会下载模型。参见 ADR 0006。
@psraghuveer/memento（CLI）	已发布的 memento 二进制文件（npx @psraghuveer/memento 或 npm i -g @psraghuveer/memento）。生命周期命令（init、serve、dashboard、context、doctor、verify-setup、status、ping、backup、export、import、pack、store migrate、completions、explain、skill-path、uninstall），以及对注册表接口的通用映射（memento <namespace> <verb>）。参见 docs/reference/cli.md。
@psraghuveer/memento-dashboard	本地优先的 Web 仪表板。进程内的 Hono 服务与引擎搭配使用，前端为通过 Vite 构建的 React SPA。通过 memento dashboard 启动；仅绑定到 127.0.0.1。参见 ADR-0018 和 docs/guides/dashboard.md。
@psraghuveer/memento-landing	营销落地页。静态 SPA；每次推送到 main 且涉及 packages/landing/** 时，都会部署到 GitHub Pages。采用与仪表板相同的设计令牌；支持浅色 / 深色切换。私有（不发布到 npm）。