Memento

Memento

为你的 AI 工具提供持久记忆，让每次会话都能从上次结束的地方继续。

你的 AI 每次会话都会从头开始。Memento 解决了这个问题。

它运行在你的机器上，可连接任何兼容 MCP 的 AI 工具，并从对话中构建持久化知识图谱——实体、关系、决策和上下文都会在每次会话重启后保留下来。

无需云服务。无需 API 密钥。无需订阅。你的数据保留在自己的机器上。

---

快速开始

前置条件：Docker — 或 — Go 1.23+ + Node.js 18+ + Ollama

git clone https://github.com/scrypster/memento.git
cd memento
./launch.sh

脚本会检测你的环境、运行预检、构建所有内容，并**在最后打印连接 AI 工具所需的准确命令。**首次运行会下载 Ollama 模型（约 5 GB）。之后只需几秒即可启动。

你的第一条记忆

连接后，在 Claude 中试试：

"We're using PostgreSQL — chose it for pgvector support."

关闭标签页，开启一个新会话，然后询问：

"What database are we using?"

你的 AI 已经知道答案。无需重新解释，也无需耍上下文窗口的技巧。

关闭标签页，开启一个新会话。

You: "What database are we using?"

→ Your AI already knows: "PostgreSQL — you chose it for pgvector support."
  No re-explaining. No context window tricks. It just remembers.

在后台，Memento 会自动构建出这样的内容：

每个实体都会连接到知识图谱中——人物、工具、项目、决策——并附有置信度评分和时间戳。

---

连接你的工具

打开 http://localhost:6363/integrations — Web UI 会为每个客户端生成配置，提供下载按钮并支持连接测试：

客户端	设置
Claude Code	运行 ./launch.sh — 脚本会在最后打印可直接复制粘贴的准确命令。示例格式：claude mcp add memento -- `pwd`/memento-mcp
Claude Desktop	下载配置 → 放入 ~/Library/Application Support/Claude/
Cursor	下载配置 → 放入 .cursor/mcp.json + 可选的 Cursor Rules 文件
Windsurf	下载配置 → 放入 .codeium/windsurf/mcp_config.json
OpenClaw	在 mcpServers 下添加到 ~/.openclaw/mcp.json — 与 Claude Desktop 使用相同格式
通用 MCP	任何 MCP 客户端 — 格式相同：命令路径 + MEMENTO_DATA_PATH 环境变量

集成页面会生成可直接粘贴的配置，其中包含你实际使用的二进制文件路径和数据目录。此外还提供连接测试、故障排除和按项目隔离的工作区。

让 Claude Code 主动使用记忆（推荐）

MCP 连接会让工具可供使用，但 Claude 不会自动使用它们。将以下内容添加到 ~/.claude/CLAUDE.md，即可让 Claude 无需提示就存储决策并回忆上下文：

## Memento MCP — Persistent Memory

The `memento` MCP server provides persistent cross-session memory. Use these tools proactively — don't wait to be asked.

**Store** (`store_memory`) when the user:
- States a preference or working style ("I prefer X", "always use Y format")
- Makes an architectural or technical decision
- Establishes project context that should survive session restarts
- Explicitly says "remember this" or similar

**Recall** (`recall_memory` or `find_related`) when:
- Starting a session for a known project — query for relevant context before diving in
- About to make a recommendation — check for existing preferences first
- The user asks about past decisions, choices, or "what did we decide about X"
- Something seems like it may have been discussed in a prior session

**Don't store:** transient debug output, in-progress exploration, or anything session-specific that won't matter next time.

Memories are searchable immediately after storing. Enrichment (entity/relationship extraction) runs asynchronously via local Ollama.

Web UI 中的 Integrations → Claude Code → Make it proactive 会生成包含你特定路径和连接设置的版本，并提供下载按钮。

查看完整的集成指南：Claude Code | Claude Desktop | Cursor & Windsurf | OpenClaw

团队记忆 — 整个工程团队共享知识

让每个人的 AI 工具都连接到同一个 Memento 实例，团队的决策、规范和上下文就会成为共享知识，任何人都可以查询，并能追溯到记录者。

每条记忆都会标记记录者。Memento 会从你的 git 配置中自动检测记录者，也可以手动设置：

export MEMENTO_USER=alice   # or set in your shell profile

或者在 MCP 配置中设置：

"env": { "MEMENTO_USER": "alice" }

设置完成后，你可以这样提问：

What did Bob decide about the auth service this week?
recall_memory(created_by="bob", created_after="2024-01-14T00:00:00Z")

设置： 每位团队成员都运行 Memento，并连接到同一个 PostgreSQL 数据库。个人上下文仍为个人所有（请使用单独的个人连接）。共享的架构决策、规范和项目上下文则存入共享连接。

完整的 PostgreSQL 配置请参阅团队设置指南。

---

AI 能做什么

连接后，AI 可以调用 20 个工具，无需额外提示：

核心记忆操作

工具	功能
store_memory	保存决策或上下文 — 增强处理在后台异步进行，响应时间低于 10ms
recall_memory	按 ID、自然语言查询或带筛选条件的分页列表检索记忆
find_related	混合搜索：全文搜索 + 语义向量 + RRF 排序
update_memory	编辑现有记忆的内容、标签或元数据
forget_memory	软删除记忆（设有宽限期），或永久硬删除

搜索与智能分析

工具	功能
traverse_memory_graph	沿实体关系查找上下文相关的记忆（多跳 BFS）
detect_contradictions	查找相互冲突的关系、已被取代但仍处于活动状态的记忆，以及时间上的矛盾
explain_reasoning	说明针对某个查询为何检索到特定记忆
get_session_context	“我上次做到哪了？”— 按主题归类近期记忆

记忆生命周期

工具	功能
update_memory_state	推进记忆生命周期：planning → active → paused / blocked / completed → archived
evolve_memory	创建取代旧版本的新版本 — 保留完整历史记录
consolidate_memories	在 LLM 协助下，将多条相关记忆合并为一条连贯记录
get_evolution_chain	查看某条记忆从最初版本到最新版本的完整历史

软删除与恢复

工具	功能
restore_memory	恢复软删除的记忆
list_deleted_memories	浏览仍可恢复的软删除记忆
retry_enrichment	对此前处理失败的记忆重新运行实体提取

项目管理

工具	功能
create_project	创建项目记忆，可选择预先创建阶段
add_project_item	在项目下添加史诗、阶段、任务、步骤或里程碑
get_project_tree	获取项目完整的嵌套层级结构
list_projects	列出所有项目，可按生命周期状态筛选

保存操作的响应时间低于 10ms。 增强处理 — 实体提取、关系映射、嵌入生成 — 都在后台异步进行。AI 不会因此受阻。

---

效果展示

自动提取实体 — 无需手动输入

人物、项目、工具、组织、编程语言、API — 都会从 AI 对话中自动提取，无需添加标签。

关系智能分析

AI 能了解谁 works_on 什么、哪些工具 depend_on 哪些服务，以及每项决策的当前状态 — 并提供置信度分数和时间戳。

仪表板

实时增强处理队列、实体浏览器、关系探索器和图可视化工具 — 全部集成在 Web UI 中。

---

为什么选择 Memento

与 Mem0 对比

Mem0 需要云端 API 密钥，生产环境使用还需要付费套餐。Memento 完全在你的设备上通过 Ollama 运行——无需 API 密钥，无需云服务，也不按记忆收费。Memento 还提供完整的 Web UI，包含图谱可视化、实体浏览器和一键集成设置。Mem0 没有 Web 界面。

与 Zep / Graphiti 对比

Zep 的知识图谱需要 Neo4j 或 FalkorDB。Memento 使用 SQLite（零依赖）或 PostgreSQL——无需管理图数据库。Zep 的开源版本功能有限；完整功能集需要 Zep Cloud。

与内置 AI 记忆（ChatGPT、Claude）对比

内置记忆只是平面的事实列表，没有关系、搜索或图谱，也无法导出或控制你的数据。Memento 为你提供由你掌控的结构化知识图谱，支持混合搜索和完整的生命周期管理。

与编写文档或维基相比

Memento 会在你工作时自动捕获上下文——无需手动操作。它会构建概念之间的关系，而不是生成互不相关的页面，并且专为大模型查询而设计，而不只是供人阅读。

---

工作原理

┌─────────────────────────────────────────────────────┐
│  Your AI tool (Cursor / Claude Code / Windsurf / …) │
└─────────────────────────┬───────────────────────────┘
                          │  MCP (JSON-RPC 2.0 over stdio)
┌─────────────────────────▼───────────────────────────┐
│                   MCP Server                        │
│   store · recall · find_related · contradictions…   │
└─────────────────────────┬───────────────────────────┘
                          │
┌─────────────────────────▼───────────────────────────┐
│                Memory Engine                        │
│  ┌──────────────────────────────────────────────┐  │
│  │           Enrichment Pipeline                │  │
│  │  entity extraction → relationship mapping    │  │
│  │  → semantic embeddings → contradiction check │  │
│  └──────────────────────────────────────────────┘  │
└──────────────────┬──────────────────────────────────┘
                   │
       ┌───────────┴───────────┐
       │                       │
┌──────▼──────┐       ┌────────▼────────┐
│   SQLite    │       │  PostgreSQL     │
│  FTS5 index │       │  + pgvector     │
│  (default)  │       │  (scale-out)    │
└─────────────┘       └─────────────────┘

---

功能

完全离线运行

• Ollama 在本地运行——默认设置绝不会发起外部网络调用
• SQLite 数据库是一个由你掌控的单一文件：~/.memento/memento.db
• 需要更强的提取能力时，可切换到 OpenAI 或 Anthropic——仅在你主动选择时启用

混合搜索

• 将 FTS5 全文搜索与语义向量搜索结合，并通过倒数排名融合（RRF）进行融合
• 找到你想表达的内容，而不只是你输入的字词

知识图谱

• 提取 22 种实体类型：人物、项目、工具、语言、API、数据库、概念等
• 映射 44 种关系类型，并为其标注置信度
• 在 Web UI 中交互式探索图谱

记忆生命周期

• 生命周期状态：planning → active → paused | blocked | completed | cancelled → archived
• 衰减评分——过时的上下文会自然降低排名权重
• 访问频率加权——你经常回忆的记忆会保持醒目

可用于生产环境的后端

• SQLite（零依赖，不使用 CGo），适用于个人或本地使用
• PostgreSQL + pgvector + ivfflat 索引，适用于团队或生产部署

多连接隔离

• 为每个项目、客户端或工作区分别设置独立的记忆命名空间
• 只需一个环境变量，即可将 MCP 调用路由到不同连接

Web UI

• 仪表板提供实时丰富队列、实体浏览器、关系浏览器和图谱可视化工具
• 为每个受支持的客户端提供一键集成设置
• 连接测试、CLAUDE.md 生成、Cursor Rules 下载
• 跟踪未识别的大模型实体类型，方便你逐步扩展分类体系

---

大模型提供商

提供商	设置	使用场景
Ollama（默认）	docker compose up — 自动配置	优先保护隐私、无需 API 费用、完全离线
OpenAI	设置 MEMENTO_LLM_PROVIDER=openai + API 密钥	需要更强的提取质量，且可以使用云服务
Anthropic	设置 MEMENTO_LLM_PROVIDER=anthropic + API 密钥	需要最强的推理能力，且可以使用云服务

可以为每个连接切换提供商——不同项目可以使用不同的大模型。

---

配置

变量	默认值	说明
MEMENTO_PORT	6363	Web UI 和 REST API 端口
MEMENTO_STORAGE_ENGINE	sqlite	sqlite 或 postgres
MEMENTO_DATA_PATH	./data	SQLite 数据库目录
MEMENTO_LLM_PROVIDER	ollama	ollama、openai 或 anthropic
MEMENTO_OLLAMA_URL	http://localhost:11434	Ollama API 端点
MEMENTO_OLLAMA_MODEL	qwen2.5:7b	提取模型
MEMENTO_EMBEDDING_MODEL	nomic-embed-text	嵌入模型
MEMENTO_OPENAI_API_KEY	—	OpenAI API 密钥
MEMENTO_ANTHROPIC_API_KEY	—	Anthropic API 密钥
MEMENTO_DEFAULT_CONNECTION	—	用于多工作区隔离的默认连接名称
MEMENTO_CONNECTIONS_CONFIG	—	多工作区配置所用 connections.json 的路径
MEMENTO_BACKUP_ENABLED	false	自动备份
MEMENTO_BACKUP_INTERVAL	24h	备份频率

PostgreSQL

docker compose --profile postgres up -d

MEMENTO_STORAGE_ENGINE=postgres
MEMENTO_DATABASE_URL=postgres://memento:memento_dev_password@localhost:5433/memento

---

项目结构

memento/
├── cmd/
│   ├── memento-mcp/        # MCP server binary — connect this to your AI client
│   ├── memento-web/        # Web dashboard — entity browser, graph explorer, settings
│   └── memento-setup/      # Interactive setup wizard
├── internal/
│   ├── api/mcp/            # MCP JSON-RPC server — 20 tool handlers
│   ├── engine/             # Memory engine, enrichment pipeline, async workers
│   ├── llm/                # Ollama, OpenAI, Anthropic + circuit breaker
│   └── storage/
│       ├── sqlite/         # SQLite with FTS5 and hybrid vector search
│       └── postgres/       # PostgreSQL with pgvector and ivfflat index
├── web/
│   ├── handlers/           # HTMX handlers
│   ├── templates/          # Dashboard, graph, entities, settings, integrations
│   └── static/templates/   # MCP config snippets generated per client
├── docs/
│   └── integrations/       # Per-client integration guides
├── migrations/             # SQL schema migrations
└── docker-compose.yml

---

贡献

欢迎提交 Issue 和 PR。开始重要工作前，请先提交 Issue。

go test ./...

go build -o memento-mcp ./cmd/memento-mcp/
go build -o memento-web ./cmd/memento-web/
go build -o memento-setup ./cmd/memento-setup/

---

许可证

MIT — 请参阅 LICENSE。

---

构建者

MJ Bonanno — 软件架构师，也是 Scrypster 的创始人。

---

记住一切。永不遗忘。 与 Leonard Shelby 不同，你的上下文会一直留存——可搜索、可版本管理，并由永不消退的知识图谱提供支持。