@hasna/mementos

中文文档
0.17.11发布于 2026/10/31Apache-2.0TypeScriptES Module近 30 天下载 5.8万

AI代理的通用内存系统 - CLI + MCP服务器 + 库 API

中文使用文档
文档目录16 节
  1. 安装
  2. 快开始
  3. 国 际
  4. 任择决定援助
  5. MCP 磁共振
  6. (原始内容存档于2013-10-12) (英语). REST API
  7. 存储
  8. 客户端存储选择
  9. 服务器后端和 HTTP 客户端
  10. 托管客户——一个证书链
  11. 类型脚本 API
  12. 共享事件 Webhooks
  13. 发展
  14. 文档
  15. 许可证
  16. Claude 代码停止钩

@hasna/mementos (英语)

AI代理的持续内存,作为CLI,MCP服务器,REST服务, 和 TypeScript 库。 托管客户使用经认证的Mementos HTTP API; 本地 SQLite 只能通过明确的本地模式选择使用.

npm License

安装

医疗要求 阿宝 1.0或运行时更新.

npm install -g @hasna/mementos
# or
bun add -g @hasna/mementos

软件包安装了三个二进制:

二进制目的
mementos内存、代理、项目、图表、会话和维护CLI
mementos-mcpMCP 服务器; 默认情况下可流式 HTTP, 应请求 stdio
mementos-serveREST API 服务器

快开始

必须明确选择本地模式 。 在选入后创建的第一个命令 和迁移 ~/.hasna/mementos/mementos.db。 。 。 .

export HASNA_MEMENTOS_LOCAL=1
mementos save project-stack "Bun, TypeScript, SQLite" \
  --scope shared --category fact
mementos recall project-stack
mementos search "TypeScript"
mementos list --scope shared

在记忆需要明确所有权时登记代理人和项目:

mementos projects --add --name my-project --path "$PWD"
mementos register-agent marcus --role coding-agent
mementos inject --project "$PWD" --agent marcus --format compact

内存范围为 global, (中文(简体) ), shared, (中文(简体) ), private,以及 working。 。 。 . working 实值 瞬间会话抓取空间并默认为1小时寿命. 类别 为: preference, (中文(简体) ), fact, (中文(简体) ), knowledge, (中文(简体) ), history, (中文(简体) ), procedural,以及 resource。 。 。 .

用于CLI context 财务报告和审定财务报表 inject,明确 --project 必须解决注册的 并且将每个包含的范围限制在该精确的项目。 SDK 软件 getContext({ project_id }) 使用相同的精确项目规则。 未知的明确 在选择或触摸记忆前项目失败; 省略项目保存 现有范围选择.

图书馆和MCP注入战略保留未指定代理-私人背景 与选定项目的私人记忆相伴。 他们排除了私人记忆 分配给另一个项目。 它们现有的全球/共同政策仍然是: 图书馆战略包括各项目和项目范围的全球记忆 共享记忆; 直接 MCP 注入也会将全球记忆标注到项目中, 而它的全智能管道 使用图书馆政策.

注射项目参考文献可以是稳定的项目ID、注册名称,或 已注册路径 。 库、 MCP 和 HTTP/ SDK 注入一次解析该引用 并使用每个下游配置、搜索、过滤、钩子的稳定项目ID, 和触摸路径.

API 和 SDK 的列表 include_unassigned_project: true 与 project_id 为这个工会。 过滤器在页化之前适用,并规范 total· ; 没有任何效果。 保持精确的项目匹配.

国 际

任择决定援助

决策协助是: 默认关闭。不需要提供者账户或密钥 对于普通的 Mementos 命令。 配置并启用您想要的特性 cLI; 没有网络设置 。 这没有添加服务侧配置, 并且确实 不更改常规 search、上下文注入或合并.

mementos decisions status --json
mementos decisions configure --provider openrouter --model typesafe/jev-1.13
mementos decisions enable --retrieval --relationships
# Supply OPENROUTER_API_KEY through your secret manager's process environment.
mementos --project my-project decisions search "release approval policy" --limit 10 --json
mementos decisions evaluate --input pair.json --json
mementos decisions disable

对于快速钩子, mementos prompt-context --enabled --input - 接受JSON协议 包含 prompt, (中文(简体) ), project 和可选的明镜滤镜。 它返回一个 绑定,只读上下文接收. 无 --enabled 它不进行检索; 提供者的决定仍需要它们单独选择加入。 Hooks 应用程序注册 本地活动 hooks install mementos-context --target codex (另见: claude 或者说 codewith) (中文(简体) ). 见 即时钩设置 环境授权、项目范围、提供者披露和本土信任.

configure 援助总是无法使用. enable 只允许选定的 特性,并明确允许将其文本发送给配置的提供者. 密钥读取自 OPENROUTER_API_KEY; 从未保存在决定设置中. status 报告关键存在,而不核查或拨打提供者。 设置 在 Mementos 数据根的版本客户端偏好 decisions.json· ; 更新拒绝同时更改. status,配置,以及 evaluate 别 打开存储器或需要主机Mementos账户.

decisions search 使用现有项目获取一个有界限的候选集, 代理、会话、范围、类别和标签过滤器,然后可选地重新排序。 每个 候选人保留; 链接保留原顺序。 钥匙不见了, 超时, 无效的答案, 超大小的输入, 或提供者失败, 原始 命令返回时有明确的评估理由。 此命令没有 页形光标:它的收件名称 ranking_scope: "returned_candidates" 财务报告和审定财务报表 报告 has_more常规 search 为了帕吉尼恩 JSON包括紧凑 片段和源ID/版本,有128个KiB输出上限.

evaluate 接受 JSON 文件或 stdin (--input -) (中文(简体) ). 一种关系投入是:

{
  "task": "relationship",
  "candidates": [
    { "id": "a", "text": "Production deployment requires approval." },
    { "id": "b", "text": "Production deployment does not require approval." }
  ]
}

为相关性,使用 "task": "relevance",无空 "query",则a "candidates" 相同数组 {id,text} 形状。 关系建议是: equivalent, (中文(简体) ), complementary, (中文(简体) ), contradictory, (中文(简体) ), unrelated,或 uncertain。 。 。 . 评价只读:建议绝不授权写作或替换源 权威、人文审查或版本检查。 不可用的评价出口2; 禁用评价退出 0 有明确的 disabled 收讫.

内置适配器称OpenRouter的"决定"API有被固定的型号ID, 没有自动重试, 供应商倒置 。 默认绑定每个 对20名候选人、16 000个系列输入字符和5个 秒; 以 --max-candidates, (中文(简体) ), --max-input-chars,以及 --timeout-ms。输入文件仅限于256 KB和供应商对 64 KiB (英语). 只有查询和候选文本到 OpenRouter; 任意元数据和 候选人身份证除外。 已知的秘密模式和具有证书的 URL 在传输前进行编辑。 校正为 heuristic : 启用此选项仅用于 内容允许您发送到指定的提供者.

Jev 返回判断,而不是生成记忆或嵌入. 它的信心是 分配浓度, 并非正确概率缩入 模式和标准使请求可以复制,但不能保证确定性 提供者回答。 保持结构论证和授权确定性.

其他提供者,包括地方执行,可以实施公众 DecisionProvider 界面; 调用者不需要 OpenRouter 依赖 :

import { assessDecisions, rankDecisionCandidates } from "@hasna/mementos/sdk";
import type { DecisionProvider } from "@hasna/mementos/sdk";

// `provider` is your adapter implementing DecisionProvider.
async function rank(provider: DecisionProvider, query: string,
  candidates: Array<{ id: string; text: string }>) {
  const assessment = await assessDecisions({ task: "relevance", query, candidates }, {
    enabled: true, retrieval: true, provider: provider.id, model: provider.model,
  }, { provider });
  return { assessment, candidates: rankDecisionCandidates(candidates, assessment) };
}

知识消费者可以重新使用这一合同,以评估已经得到授权的合同 检索可能相互冲突的段落。 来源引用, 由消费者负责.

mementos --help
mementos <command> --help

人可读列表和搜索命令是紧凑并默认相接的. 使用 --limit 与 --cursor 或者说 --offset, (中文(简体) ), --verbose 用于更广泛的片段,以及 mementos show <id> 为完整的记录.

JSON收集输出在这个小版本中是故意以信封为基础的. projects --json, (中文(简体) ), agents --json, (中文(简体) ), list --json,以及 search --json 不再继续 返回赤子数组: 每个返回一个紧凑的集合和真实的集合 _meta 继续字段. --agent-json 仍然是清单收据的别名. --full 更改信封内的行细节; --all 查询已用尽 信封内(可达10万行/64米B). 旗子都不恢复光线 这四个命令的阵列。 唯一的遗产是赤裸裸的逃脱 export --all,因为导出是一个明确面向批量的命令.

JSON探员使用相抵平分法 稳定的ID连接器防止重叠 等同时间戳和重要性,而结果集不变; 写 在页面请求之间可以移动相抵,所以当一个稳定时重新启动倒转 需要快照.

mementos list --json                         # compact 20-row receipt, <=32 KiB
mementos list --json --cursor 20
mementos list --json --full --limit 5        # explicit full detail, still bounded
mementos list --json --all                   # exhaustive receipt, still an envelope
mementos projects --json                     # compact continuation receipt
mementos agents --json                       # compact continuation receipt
mementos search "deploy" --json              # compact byte-capped search receipt
mementos export                              # truthful paginated export receipt
mementos export --all                        # explicit exhaustive legacy array
mementos storage mode --json

完整的命令树和选项常规在 CLI 参考。 。 。 .

MCP 磁共振

mementos-mcp 默认为共享、 无国籍的 HTTP 服务器 127.0.0.1:8867数字 :

mementos-mcp
# explicit equivalent
mementos-mcp --http --port 8867

终点是 GET /health 财务报告和审定财务报表 POST /mcp设置 MCP_HTTP_PORT 更改 端口 。 对于一个启动一个比 stdio 以上程序的儿童过程的 MCP 主机,明确选择:

mementos-mcp --stdio
# or: MCP_STDIO=1 mementos-mcp

Cursor, Codex, Claude, 以及其他基于命令的 MCP 主机条目应该使用 command = "mementos-mcp" 与 args = ["--stdio"]。 。 。 .

默认 core MCP剖面暴露出一个有边框的23个工具剂表面. 选择 附加逗号分隔配置文件 --mcp-profile, (中文(简体) ), HASNA_MEMENTOS_MCP_PROFILE,或兼容性别名 MEMENTOS_MCP_PROFILE数字 : search, (中文(简体) ), graph, (中文(简体) ), automation, (中文(简体) ), admin, (中文(简体) ), storage, (中文(简体) ), hooks,以及 full明确 full 配置保存所有124个工具和 遗留未页 mementos://memories, (中文(简体) ), mementos://agents,以及 mementos://projects 资源; 缩小配置忽略这些资源和使用 限定列表/ 获取工具 .

MCP 磁共振 tools/list 仍然是权威的策略来源. search_tools 返回时 用于活动描述工具的限定名称页,以及 describe_tools 需要一到十个明确的名字. memory_context 默认为十等 32 KiB 上限下 ~ 240 字符预览; 使用 detail="full" 当然. memory_inject 默认为轻量级提示并保存完整的注射 后面 mode="full"。 。 。 . memory_export 被标注并带有收据。 见 MCP 参考 页:1 配置会员和相容性细节.

(原始内容存档于2013-10-12) (英语). REST API

mementos-serve --port 19428

服务器绑定到 127.0.0.1 除非 MEMENTOS_HOST 已经设定. /v1 这是 犬科API 前缀和 /api 是后相兼容的别名。 业务 探测器和生成的合同无需认证即可提供:

GET /health
GET /ready
GET /version
GET /openapi.json

API 路由在配置时使用无记名/API- key认证. 见 REST API 参考文献。 。 。 .

存储

客户端存储选择

主机Mementos API是普通客户端默认. CLI,MCP服务器, 和 SDK 解析下述主机证书和权威链 没有主机证书解析, 客户端数据命令失败而不是关闭 自动打开或创建 SQLite.

SQLite 只能通过明确的本地选入:

# Use the standard local data root (~/.hasna/mementos/mementos.db).
export HASNA_MEMENTOS_LOCAL=1

# Or select one exact SQLite file explicitly.
export HASNA_MEMENTOS_DB_PATH=/absolute/path/to/mementos.db

MEMENTOS_LOCAL=1 财务报告和审定财务报表 MEMENTOS_DB_PATH 是相容性别名。 遗产 ~/.mementos 只有在本地模式完成后才考虑迁移数据 明确选中; 它从来不是自动客户端倒置 .

服务器后端和 HTTP 客户端

没有部署模式 。 唯一的运行时间开关是服务器数据 后端 : sqlite | postgresql选择 HASNA_MEMENTOS_DATABASE_URL 存在。 Raw PostgreSQL 证书是仅服务器的 —— 配置 mementos-serve 与 HASNA_MEMENTOS_DATABASE_URL; 配置 CLI 和 MCP hTTPS API 端点和 API 键的客户端 :

# mementos-serve environment
HASNA_MEMENTOS_DATABASE_URL=postgres://...

# client environment; do not distribute the database URL to clients
HASNA_MEMENTOS_API_URL=https://mementos.example.com
HASNA_MEMENTOS_API_KEY=...

托管客户——一个证书链

CLI、MCP服务器和 ./sdk 客户解决其证书和 通过在 @hasna/contracts (单位:千美元)@hasna/contracts/client{\fn黑体\fs22\bord1\shad0\3ahbe\4ah00\fscx67\fscy66\2chffffff\3ch808080}每个电话都新鲜了 {\fn黑体\fs22\bord1\shad0\3ahbe\4ah00\fscx67\fscy66\2chffffff\3ch808080}所以按键旋转可以治愈 不重新启动的长寿命 shell 或 MCP 服务器 :

级别来源
1个明确的论点--api-key 编号 : --profile,或 baseUrl 编号 : apiKey 在SDK中)
2个故意嵌入指针 : HASNA_MEMENTOS_API_KEY_OVERRIDE, (中文(简体) ), HASNA_PROFILE, (中文(简体) ), HASNA_MEMENTOS_API_KEY_REF (一个密- 错误项密钥, 绝不是一个值)
3个macOS 密钥链: 通用密码 hasna.credentials.mementos.api-key账户 HASNA_STATION → hostname -s → USER
页:1磁盘 : ~/.hasna/mementos/config/credentials,仅限所有者 0400编号 :0600 (单位:千美元)HASNA_HOME 编号 : HASNA_CONFIG_HOME 移动根)
页:1环境: HASNA_MEMENTOS_API_KEY

授权如下: HASNA_MEMENTOS_API_URL键链 api-url 项目, 最后是舰队网关 https://api.hasna.com/mementos - 证明人身份是完整的 配置 。 无前缀的遗产 MEMENTOS_API_URL 编号 : MEMENTOS_API_KEY 拼写只能随着解析器的无声化名为一而终 释放。 写入磁盘级的密钥 :

mkdir -p ~/.hasna/mementos/config
printf 'HASNA_MEMENTOS_API_KEY=%s\n' "$KEY" > ~/.hasna/mementos/config/credentials
chmod 600 ~/.hasna/mementos/config/credentials

FAIL LOUD(业主裁决2026-09-04):在任何地方没有证书的东道主跑道 退出非零命名其所咨询的每个级别;没有SQLite倒置和 没有本地倒计时事件 。 盒装的 SQLite 商店只能通过 故意选择进入 HASNA_MEMENTOS_DB_PATH 编号 : MEMENTOS_DB_PATH (明确 文档)或 HASNA_MEMENTOS_LOCAL=1 (别名) MEMENTOS_LOCAL=1只有在 无任何配置权威)——每个本地运行都打印出一行字来表示 这是本地的 Stderr。 退休地点~/.hasna/fleet-env/, (中文(简体) ), ~/.hasna/cloud/, (中文(简体) ), ~/.config/hasna/, (中文(简体) ), $XDG_CONFIG_HOME)和已退休 *_MODE 编号 : *_STORAGE_MODE 变量没有输入.

mementos storage mode 报告所选运输方式,而不打开 数据库或网络请求; mementos status 打印已解决 API: 线条(hasna/apps#1588).

旧的 storage push, (中文(简体) ), pull,以及 sync 为兼容性保留命令; 他们不是剪接结构 见 配置和 存储 编辑 云切分运行簿。 。 。 .

类型脚本 API

主软件包导出同步数据库/域名 API @hasna/mementos 和认证的客户端 @hasna/mementos/sdk - 一个包每个表面(CLI、MCP服务器、REST服务器、SDK) 不分开 -sdk 或者说 -mcp 软件包。 见 图书馆和SDK API。 。 。 .

共享事件 Webhooks

CLI包括: events 财务报告和审定财务报表 webhooks 命令组 @hasna/events,允许内存事件触发命令或HTTP自动化. 在配置 Webhook 之前查看他们的安装版本帮助 :

mementos events --help
mementos webhooks --help

事件命令处理器在 stdin 和 in 上接收信封 HASNA_EVENT_JSON。包含 working_dir, (中文(简体) ), project_path,或 repo_path 当 a 下游代理必须运行在一个特定的寄存器中.

发展

bun install
bun run typecheck
bun test
bun run build

发展切入点是: bun run dev:cli, (中文(简体) ), bun run dev:mcp,以及 bun run dev:serve。 。 。 .

文档

许可证

阿帕奇-2.0 — 见 自由主义。 。 。 .

Claude 代码停止钩

预览已安装的 CLI 管理钩头配置 :

mementos session setup-hook --claude

应用精确的预览 --apply --expect-settings-sha256 <digest> (或 absent 用于新建设置文件。 公认的后遗症钩也需要 --expect-hook-sha256 <digest>。安装器保留无关的设置, 保留原始设置作为私人备份,并拒绝自定义或更改 钩子文件. 连线 .claude 目录被保存并需要预览 --expect-directory-sha256 <digest>; 重新瞄准别名使预览无效 即使其设置有相同的字节. mementos init 使用相同的安装器,而不启动本地端 当主机API配置时,服务器.

当技能管理克劳德的本土发现时,安装将验证 现有审查和更新Stop钩及其发现证人. 现有的插件、权限、本地技能或钩子漂移拒绝安装; 它从未被默默地采纳。 没有技能政策的设施保留 独立的行为。 技能只在应用安装时加载. 安装器使用已公布的 Swill 0.9.14 SDK 并明确支持 审查了v2设置和市场证人。 他们允许的模范努力和 市场时间戳更改仍然有效;安装器无法启用 v2 自行审查或作出无关的修改.

安装站台上自有的 CLI 入站点名称 – the 进入点 ~/.local/bin/mementos 先说 ~/.bun/bin/mementos ——在 便携式外壳形式 "$HOME/.local/bin/mementos" session stop-hook --claude这样 stop 勾钩不依赖于 Claude 的 PATH 和设置复制或恢复 继续在家里工作 既不是版本软件包缓存路径,也不是 特定车站的家被冻结在克洛德的配置中;入口 symlink拥有运行时间和版本. 当两个入口都不存在时 已公布的便携式命令 mementos session stop-hook --claude 保留 安装了窗体并需要克洛德PATH上所安装的CLI. 这个 读取本地人 transcript_path 和最后助理人员 文本,不包括工具有效载荷,编辑已知的秘密模式,并通过 普通主机证书解析器 。 它从不吞噬钩子信封 对话 回到本地商店 或自动重复模糊 提交。 失败者报告一个固定的、没有私人数据的阶段和原因,例如 [phase=request; reason=timeout],并在可用时使用 HTTP 实际错误状态. 输入、记录、配置、请求和反应失败是不同的; 例外消息、记录路径、证书和服务器机构不得进入 诊断 中断的请求可能已经到达服务器,所以 失败不能证明没有创建工作。 钩子在故障后1出入口, 报告它而不阻碍克洛德的停止 Claude钩出厂码合同。 。 。 . 钩子只发出新东西 它保持每段光标( 字节) 页:1 包裹状态之家, $HASNA_STATE_HOME/mementos/claude-stop/ 或 每个站点都从光标上读取。 对话文本为 jSON身体停留在服务器下方或低于768KiB的部分发送 1 MiB 请求受约束;一个超过一部分的文本被分割并被片段恢复. 光标只在服务器接受一部分后才推进,所以拒绝的部分是 下一站又派来了 什么都没有损失 每站扫描最多128个米B 最多发送四个部分;下一站继续积压,因此没有 笔录太大了 超过8个米B的JSONL记录是一个工具有效载荷 在不解析的情况下跳过,并报告计数。 替换 记录从头看一遍 一个会话停止重叠 永远不要两次发送相同的条目: 第二个将作品留给第一个. 到达服务器的中断请求在下一站再次发出, 这样一部分可以摄入两次。 输入上下文为64 KiB. 何时 MEMENTOS_AGENT 被配置, 钩子保存代理属性 . 安装者还承认历史上最吸食CLI的迁徙 精确摘要; 修改后的副本仍作为自定义钩子保护.

版本与发布记录

@hasna/mementos 共发布 169 个版本,首次发布于 2026/03/10;过去 12 个月发布了 169 个版本。

版本发布日期距今
0.17.11latest2026/10/3117 天前
0.17.102026/10/161 个月前
0.17.92026/10/161 个月前
0.17.82026/09/241 个月前
0.17.72026/09/231 个月前
0.17.62026/09/221 个月前

其他发布通道:release-candidate-0.14.78 → 0.14.78,release-candidate-0.14.79 → 0.14.79,release-candidate-0.14.80 → 0.14.80,release-candidate-0.14.81 → 0.14.81,release-candidate-0.14.82 → 0.14.82,release-candidate-0.14.83 → 0.14.83。

关于 @hasna/mementos 的常见问题

@hasna/mementos 是什么?

AI代理的通用内存系统 - CLI + MCP服务器 + 库 API

如何安装 @hasna/mementos?

在项目目录运行 npm install @hasna/mementos,或使用 pnpm add / yarn add / bun add。它还提供命令行工具 mementos、mementos-mcp、mementos-serve,可以用 npx mementos 直接运行。

@hasna/mementos 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@hasna/mementos 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@hasna/mementos 可以商用吗?

@hasna/mementos 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@hasna/mementos 的下载量有多少?

根据 npm 官方下载统计,@hasna/mementos 在 2026/10/18 – 2026/11/16 这 30 天内被下载 57,597 次,日均约 1,920 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@hasna/mementos 还在维护吗?

最新版本 0.17.11 发布于 2026/10/31(17 天前);至今共发布 169 个版本,其中过去 12 个月发布了 169 个;首次发布于 2026/03/10。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。