AI导哈

AI助手持久记忆服务

Memento是一个为AI助手提供跨会话持久记忆存储和检索的本地服务，采用两阶段检索机制和纯文件存储。

  • by Kotrotsos
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 Kotrotsos/memento-core

使用说明

纪念品

为AI助手提供持久、可搜索的内存。

Memento是一个MCP服务器，为Claude提供跨会话、项目和机器的长期内存。储存你学到的东西，稍后搜索，只回忆你需要的东西。

没有数据库。没有嵌入模型。没有外部服务。纯文件，在本地运行。

运作原理

大多数人工智能助手在会话结束时会忘记一切。Memento通过为Claude提供一个可以跨会话读写的持久存储来修复这个问题。

设计围绕 两阶段检索：search返回紧凑的片段，这样AI就可以决定什么是相关的，然后recall只获取它实际需要的条目的完整内容。这使上下文窗口保持精简，成本低。

存储仅在磁盘上附加JSONL文件。搜索是BM25，与大多数搜索引擎的概率排名相同。没有机器学习，没有API，只有快速的确定性文本匹配。

安装

选项1:克劳德代码插件

claude plugin add github:Kotrotsos/memento-core

插件通过SessionStart钩子在首次使用时自动构建（大约需要10秒）。之后就是瞬间。

选项2：手动

git clone https://github.com/Kotrotsos/memento-core.git
cd memento-core
npm install && npm run build

然后注册MCP服务器。将此添加到您的 ~/.mcp.json 或项目级别 .mcp.json:

{
  "mcpServers": {
    "memento": {
      "command": "node",
      "args": ["/path/to/memento-core/build/index.js"]
    }
  }
}

重新启动克劳德代码。你应该看看 memory_* 工具可用。

MCP工具

Memento通过模型上下文协议公开了五个工具。

memory_store

创建新内存或更新现有内存。

memory_store(content, namespace?, tags?, id?, relations?, ttl?)
参数 类型 默认值 说明
content string 必填 内存文本
namespace 字符串 "global" 在哪里归档： global, projects/my-app, decisions等等。
tags string[] [] 过滤标签： architecture, preference, bug等等。
id string auto 提供一个现有的ID来更新该内存
relations string[] [] 相关存储器的ID
ttl string 永久 ISO 8601过期。在此时间戳之后，内存将从结果中排除

示例

{
  "content": "Use JSONL for storage. Chosen over SQLite (binary, overkill) and single JSON files (can't stream/append).",
  "namespace": "decisions",
  "tags": ["architecture", "storage"]
}

memory_search

用BM25排名搜索记忆。返回片段，而不是完整内容。

memory_search(query, namespace?, tags?, limit?)
参数 类型 默认值 说明
query string 必填 搜索词
namespace string all 作用域结果到命名空间
tags string[] -- 按标签筛选（AND逻辑，所有必须匹配）
limit 编号 10 返回的最大结果

回应

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "namespace": "decisions",
    "tags": ["architecture", "storage"],
    "snippet": "Use JSONL for storage. Chosen over SQLite (binary, overkill) and single JSON files...",
    "score": 6.41,
    "updated": "2026-02-26T14:30:00Z"
  }
]

摘要是内容的前150个字符，足以在不燃烧上下文的情况下判断相关性。

memory_recall

获取特定内存ID的完整内容。使用搜索后加载您实际需要的内容。

memory_recall(ids)
参数 类型 说明
ids string[] 以前搜索的一个或多个内存ID

回应

[
  {
    "id": "550e8400-...",
    "namespace": "decisions",
    "content": "Use JSONL for storage. Chosen over SQLite (binary, overkill) and single JSON files (can't stream/append). JSONL is append-friendly, streamable, human-readable, and grep-compatible.",
    "tags": ["architecture", "storage"],
    "created": "2026-02-26T14:30:00Z",
    "updated": "2026-02-26T14:30:00Z",
    "source": "claude-code",
    "relations": [],
    "ttl": null
  }
]

memory_delete

软删除内存。该条目保留在JSONL文件中，但被排除在所有查询之外。

memory_delete(id, namespace)

memory_list_namespaces

列出所有具有条目计数的命名空间。没有参数。

[
  { "namespace": "global", "count": 42 },
  { "namespace": "projects/my-app", "count": 17 },
  { "namespace": "decisions", "count": 8 }
]

管理用户界面

Memento包括一个用于浏览和管理记忆的网络界面。

npm run admin

开放时间： http://localhost:3000.自定义端口：

MEMENTO_ADMIN_PORT=8080 npm run admin

您将获得：

  • 带有内存计数、命名空间计数、标签云和最近条目的仪表板
  • 带深入查看功能的命名空间浏览器
  • 带有元数据（标签、时间戳、源、TTL、关系）的全内存查看器
  • 通过表单创建、编辑和删除
  • BM25使用命名空间和标签过滤器进行搜索
  • 包含存储路径和磁盘使用情况的服务器信息页面

让克劳德自动使用Memento

当克劳德在会话开始时回忆上下文，并在结束前存储重要内容时，记忆碎片效果最佳。您可以使用Claude Code钩子来强制执行此操作。

1.创建挂钩脚本

~/.claude/hooks/session-start-memento.sh

#!/bin/bash
INPUT=$(cat)
PROJECT=$(basename "$(echo "$INPUT" | jq -r '.cwd // empty')" 2>/dev/null)
if [ -n "$PROJECT" ]; then
  echo "[Memento] Search Memento for relevant memories about \"$PROJECT\" before starting work."
else
  echo "[Memento] Search Memento for relevant memories before starting work."
fi

~/.claude/hooks/stop-memento.sh

#!/bin/bash
STOP_REASON=$(cat | jq -r '.stop_reason // "end_turn"')
if [ "$STOP_REASON" = "end_turn" ]; then
  echo "[Memento] Before finishing: did you store significant findings, decisions, or completed work in Memento?"
fi

chmod +x ~/.claude/hooks/session-start-memento.sh
chmod +x ~/.claude/hooks/stop-memento.sh

2.将钩子登记在 ~/.claude/settings.json

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/hooks/session-start-memento.sh",
            "timeout": 5
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/hooks/stop-memento.sh",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

3.自动允许Memento工具

将这些添加到 permissions.allow 所以克劳德从来不需要征得许可：

{
  "permissions": {
    "allow": [
      "mcp__memento__memory_store",
      "mcp__memento__memory_recall",
      "mcp__memento__memory_search",
      "mcp__memento__memory_delete",
      "mcp__memento__memory_list_namespaces"
    ]
  }
}

书写美好回忆

你得到的东西的质量取决于你储存的东西的品质。

正面加载关键信息。 BM25不关心位置，但片段显示了前150个字符。把核心事实放在第一位。

# Good
Use JSONL for storage. Chosen over SQLite (binary) and single JSON files (can't stream).

# Bad
After a long discussion about storage options, we eventually decided that JSONL would work best.

每个记忆一个概念。 单独的关注点不会竞争相关性，可以独立回忆。

始终包含标签。 没有标签的记忆只能通过全文搜索找到。

使用命名空间对域进行分段。 一个 global 包含数千个条目的命名空间会变得嘈杂。范围至 projects/my-app 或 decisions 以获得更清洁的结果。

存储布局

~/.memento/
  memories/
    global.jsonl
    decisions.jsonl
    procedures.jsonl
    projects/
      my-app.jsonl
      another-project.jsonl

每一行 .jsonl 文件是一个内存条目。写入总是附加的。更新会写入一个具有相同ID的新条目，加载程序只保留最新版本。删除并写入一个条目 deleted: true.

集 MEMENTO_HOME 更改基本目录。

配置

变量 默认值 描述
MEMENTO_HOME ~/.memento 所有存储的基本目录
MEMENTO_ADMIN_PORT 3000 管理web UI的端口

插件命令

当作为Claude Code插件安装时，有三个斜线命令可用：

命令 描述
/memento-search <query> 搜索记忆，并可选择回忆完整内容
/memento-store <content> 使用引导的命名空间和标签选择存储内存
/memento-admin [port] 启动管理web UI

技术细节

  • 建筑：设计原则、存储模型、搜索算法、上下文工程
  • 架构参考：完整字段引用、数据消除规则、响应格式
  • 上下文工程指南：渐进式披露策略、写作指南、反模式、缩放

许可证

麻省理工学院

相关 MCP