智能体持久记忆 mem9-ai/mem9

为 AI 智能体提供持久记忆。
智能体一换会话就忘光一切。mem9 解决这个问题：跨会话、跨机器保留持久记忆，多智能体工作流共享记忆，混合召回，还带可视化面板。

OpenClaw 和 ClawHub 的安装，从这里开始：mem9.ai/openclaw-memory

Hermes Agent、Claude Code、OpenCode、Codex、DeepSeek Harness 和 Dify 的指南见下文。

快速开始

1. 选择 mem9 端点。

- 托管 API：https://api.mem9.ai
- 自托管：先应用对应的控制面 schema，再启动 mnemo-server：

cd server
MNEMO_DSN="user:pass@tcp(host:4000)/mnemos?parseTime=true" go run ./cmd/mnemo-server

各后端的详细配置见自托管，开通流程见 API 参考。

2. 挑一份集成指南。

- OpenClaw / ClawHub
- Hermes Agent
- Claude Code
- OpenCode
- Codex
- DeepSeek Harness
- Dify
- 任意 HTTP 客户端 / 自定义运行时

3. 设置凭据。

Hosted API
export MEM9_API_URL="https://api.mem9.ai"
export MEM9_API_KEY="<mem9-api-key>"

Self-hosted
export MEM9_API_URL="http://localhost:8080"
export MEM9_API_KEY="<mem9-api-key>"

自托管部署请用你的服务器 URL，以及开通流程返回或配置的 mem9 API key。

为什么选 mem9

mem9 给编码智能体一层共享记忆，不用再各自维护本地笔记本和一次性的提示词文件。
| mem9 能给你什么 | 为什么重要 |
| 跨会话、跨机器的持久记忆 | 上下文能扛住重启、换笔记本和长期项目 |
| 跨智能体、跨工作流平台共享记忆 | OpenClaw、Hermes Agent、Claude Code、OpenCode、Codex、DeepSeek Harness、Dify 应用和自定义客户端能回忆同一批事实 |
| 无状态集成 | 运行时插件保持轻量，因为存储、搜索、写入和策略都在服务端 |
| 混合召回和可视化面板 | 语义搜索、关键词搜索和检查工作流都在同一套系统里 |

支持的平台和智能体运行时

| 平台 | 集成形态 | 安装 / 文档 |
| OpenClaw | kind: "memory" 插件，提供由服务端支撑的共享记忆 | OpenClaw / ClawHub 安装指南 |
| Hermes Agent | 记忆服务商插件，带配置和激活流程 | mem9-hermes-plugin README |
| Claude Code | 带钩子和技能的市场插件 | claude-plugin/README.md |
| OpenCode | 插件 SDK 集成，从 opencode.json 加载 | opencode-plugin/README.md |
| Codex | 市场插件，带托管钩子和项目级覆盖 | codex-plugin/README.md |
| DeepSeek Harness | 原生 DSH/Cordis 包，带召回、智能写入和记忆工具 | dsh-plugin/README.md |
| Dify | 工具插件，面向 Dify Agent 应用和 Workflow 应用，支持单空间和多空间授权 | mem9-dify-plugin README |
| 任意 HTTP 客户端 / 自定义运行时 | 直接集成 REST API | API 参考 |

所有支持的运行时和平台集成都暴露同一套核心记忆流程：针对 mem9 服务端 API 做存储、搜索、获取、更新和删除。

为什么用托管 API

托管 mem9 API 是给智能体集群接上持久记忆的最快方式，同时保留以后自托管的选项。

| 托管 API 能力 | 为什么团队从这里起步 |
| 托管 mem9 API，即时开通空间 | 你可以先装智能体集成，第一天不用搭基础设施 |
| 跨运行时、跨平台共享记忆 | 一个空间能同时服务 OpenClaw、Hermes Agent、Claude Code、OpenCode、Codex、DeepSeek Harness、Dify 应用和自定义客户端 |
| 托管搜索和存储 | 混合召回开箱即用，不用另搭向量栈或同步层 |
| 基于 TiDB Cloud Starter | 托管路径受益于即时开通、原生向量搜索、全文搜索、服务端自动嵌入、混合搜索和 MySQL 兼容的运维语义 |
| 与自托管 mem9 相同的 API 契约 | 迁到自己的部署只需改 base URL 和凭证，不用重写插件 |
| 可视化面板与产品引导 | 团队无需先自建内部工具，就能查看和管理记忆 |

底层实现上，托管的 mem9 API 运行的是本仓库展示的同一套 mem9 服务端模型，由 TiDB Cloud Starter 提供托管开通、原生向量搜索、全文搜索、服务端自动嵌入、混合搜索，以及兼容 MySQL 的存储语义。

API 参考

在需要鉴权的记忆、导入和会话消息请求上设置 X-Mnemo-Agent-Id，让服务端区分同一 mem9 空间内是哪个运行时或智能体实例在写入和召回记忆。租户路径的 v1alpha1 路由和 v1alpha2 的 API-key 路由都支持。

开通

想让 mem9 自动开通新的 TiDB 支撑空间时，用这个端点。

| 方法 | 路径 | 说明 |
| POST | /v1alpha1/mem9s | 配置了 provisioner 时的 TiDB 自动开通端点。TiDB Zero 在 tidb 上默认启用这条路径；TiDB Cloud Pool 用 MNEMO_TIDB_ZERO_ENABLED=false 配合 MNEMO_TIDBCLOUD_API_KEY 和 MNEMO_TIDBCLOUD_API_SECRET。手动 bootstrap 的部署改用已有租户，不走这条路径。返回 { "id" }。接受可选的 utm_ 查询参数，用于归因日志 |

新集成一律优先用 v1alpha2。它使用 X-API-Key，是当前运行时的主要 API 接口。

首选 API（v1alpha2）

| 方法 | 路径 | 说明 |
| POST | /v1alpha2/mem9s/memories | 首选统一写入端点。需要 X-API-Key 请求头 |
| GET | /v1alpha2/mem9s/memories | 首选搜索端点。需要 X-API-Key 请求头 |
| GET | /v1alpha2/mem9s/memories/{id} | 首选按 ID 获取端点。需要 X-API-Key 请求头 |
| PUT | /v1alpha2/mem9s/memories/{id} | 首选更新端点。需要 X-API-Key 请求头 |
| DELETE | /v1alpha2/mem9s/memories/{id} | 首选删除端点。需要 X-API-Key 请求头 |
| GET/POST | /v1alpha2/mem9s/webhooks | 空间 webhook 管理。需要空间的 X-API-Key |
| GET/PATCH/DELETE | /v1alpha2/mem9s/webhooks/{webhookID} | 获取、更新或删除空间 webhook |
| POST | /v1alpha2/mem9s/webhooks/{webhookID}/test | 排队一次带签名的测试投递 |
| POST | /v1alpha2/mem9s/webhooks/{webhookID}/rotate-secret | 轮换 webhook 签名密钥。新密钥只返回一次 |
| GET | /v1alpha2/mem9s/webhook-deliveries | 列出空间最近的 webhook 投递 |
| GET/POST | /v1alpha2/space-chains/{chainID}/webhooks | 空间链 webhook 管理。需要在 X-API-Key 中提供 chain_ 管理密钥 |
| GET | /v1alpha2/space-chains/{chainID}/webhook-deliveries | 列出空间链最近的 webhook 投递 |

webhook 事件与投递行为见 docs/webhooks-api-design.md。v1 会发出 memory.added、memory.deleted 和 space_chain.fact_routed。

Space Chain 管理

Space Chain 让你编排有序的多空间召回与路由流水线。每个 Space Chain 有两种 chain_ 密钥，具体是哪种由服务端判定。管理密钥能改动链（节点、密钥、webhook、删除），也能读写记忆。记忆密钥只能读写记忆；除创建链之外，下面每个端点用它都会返回 401。下面所有管理端点都用管理密钥作为 X-API-Key，只读写记忆的场合则给记忆密钥。读取节点要用节点自己 Space 的 X-API-Key。

| Method | Path | Description |
| POST | /v1alpha2/space-chains | 创建 Space Chain。不需要 X-API-Key。201 响应恰好三个字段：chain（链，密钥已打码）、management_binding 和 memory_binding。每个 binding 有 id、role 和 chain_api_key；这是你唯一能拿到明文密钥的机会，现在就存好。如果服务端开启了 create gate，请求还必须带上 Authorization: Bearer <create secret>，否则返回 401 |
| GET | /v1alpha2/space-chains/by-key | 用管理密钥查 Space Chain。X-API-Key 里要放管理密钥；记忆密钥会得到 401 |
| GET | /v1alpha2/space-chains/{chainID} | 获取 Space Chain 详情。需要管理密钥 |
| PATCH | /v1alpha2/space-chains/{chainID} | 更新 Space Chain 的名称/描述。需要管理密钥 |
| DELETE | /v1alpha2/space-chains/{chainID} | 软删除 Space Chain。需要管理密钥 |
| GET | /v1alpha2/space-chains/{chainID}/nodes | 列出链中所有节点（按位置排序）。需要管理密钥 |
| PUT | /v1alpha2/space-chains/{chainID}/nodes | 替换链中所有节点（全量替换）。需要管理密钥 |
| PUT | /v1alpha2/space-chains/{chainID}/nodes/{nodeID}/routing-policy | 更新指定链节点的路由策略。需要管理密钥 |
| GET | /v1alpha2/space-chains/{chainID}/bindings | 列出链的所有密钥（binding），每个带 role 和打码后的密钥。需要管理密钥 |
| POST | /v1alpha2/space-chains/{chainID}/bindings | 为链再签发一个密钥。签出来的永远是记忆密钥；请求体里的 role 会被忽略。请求体可选：可以带 chain_api_key 自己提供密钥（必须以 chain_ 开头），也可以带 created_by_user_id。201 响应就是新 binding：id、chain_id、role、chain_api_key（只在此刻显示）、disabled 和 created_at。需要管理密钥 |
| PATCH | /v1alpha2/space-chains/{chainID}/bindings/{bindingID} | 停用密钥。最后一个可用的管理密钥不能停用（400）；记忆密钥可以全部停用。需要管理密钥 |

其他 v1alpha2 端点

| Method | Path | Description |
| POST | /v1alpha2/mem9s/memories/batch-delete | 批量软删除记忆（最多 1000 条）。接受 {"ids": ["..."]}。需要 X-API-Key |
| GET | /v1alpha2/mem9s/session-messages | 列出已持久化的会话消息。需要 X-API-Key。查询参数：session_id、limit_per_session |
| POST | /v1alpha2/mem9s/imports | 上传 JSON 文件，异步导入（multipart，最大 50MB）。file_type：memory 或 session。需要 X-API-Key |
| GET | /v1alpha2/mem9s/imports | 列出上传任务及汇总状态。需要 X-API-Key |
| GET | /v1alpha2/mem9s/imports/{id} | 获取单个上传任务详情。需要 X-API-Key |
| GET | /v1alpha2/status | 校验 X-API-Key 请求头。返回密钥状态（active/inactive），不解析租户 |

旧版租户路径 API（v1alpha1）

仅在需要兼容旧客户端（租户 ID 放在路径里）时使用这些端点。

| Method | Path | Description |
| POST | /v1alpha1/mem9s/{tenantID}/memories | 旧版统一写入端点。租户密钥放在 URL 路径里 |
| GET | /v1alpha1/mem9s/{tenantID}/memories | 旧版搜索端点，供按 tenantID 配置的客户端使用 |
| GET | /v1alpha1/mem9s/{tenantID}/memories/{id} | 旧版按 ID 获取端点 |
| PUT | /v1alpha1/mem9s/{tenantID}/memories/{id} | 旧版更新端点。可选 If-Match 做版本校验 |
| DELETE | /v1alpha1/mem9s/{tenantID}/memories/{id} | 旧版删除端点 |

自托管

首次启动前，先应用与后端匹配的控制平面 schema：server/schema.sql、server/schema_pg.sql 或 server/schema_db9.sql。

mem9 server 支持多种存储后端。把 MNEMO_DB_BACKEND 设为 tidb、postgres 或 db9，让 MNEMO_DSN 指向对应后端，其余运行时约定对你的智能体保持不变。TiDB 支持三种租户流程：tidb 上默认启用 TiDB Zero 自动开通；TiDB Cloud Pool 自动开通需设 MNEMO_TIDB_ZERO_ENABLED=false，并配置 MNEMO_TIDBCLOUD_API_KEY 和 MNEMO_TIDBCLOUD_API_SECRET；手动引导走预置租户模式。postgres 和 db9 走高级手动引导路径，要求控制平面 DB 中存在活跃租户行，且其背后有可用的租户数据库和 schema。在 v1alpha2 中，X-API-Key 通过 ID 查找解析租户。

构建与运行

make build
cd server
MNEMO_DSN="user:pass@tcp(host:4000)/mnemos?parseTime=true" ./bin/mnemo-server

本地开发时，服务端源码变更后自动重新构建并重启：

MNEMO_DSN="user:pass@tcp(host:4000)/mnemos?parseTime=true" make dev

部署 PostgreSQL 或 db9 时，启动服务端前先导出 MNEMO_DB_BACKEND=postgres 或 MNEMO_DB_BACKEND=db9。

Docker

make docker 把镜像标记为 ${REGISTRY}/mnemo-server:${COMMIT}。下面这个本地示例构建 local/mnemo-server:dev：

make docker REGISTRY=local COMMIT=dev
docker run -e MNEMO_DSN="..." -e MNEMO_DB_BACKEND="tidb" -p 8080:8080 local/mnemo-server:dev

环境变量

最小运行时配置只需 MNEMO_DSN。其余都是可选项，或者只对特定部署模式生效。

核心服务

| 变量 | 必填 | 默认值 | 说明 |
| MNEMO_DSN | 是 | — | 数据库连接串 |
| MNEMO_PORT | 否 | 8080 | HTTP 监听端口 |
| MNEMO_DB_BACKEND | 否 | tidb | 数据库后端：tidb、postgres 或 db9 |
| MNEMO_RATE_LIMIT | 否 | 100 | 每个 IP 和 API key 的请求速率（次/秒，按 header 或旧版路径计） |
| MNEMO_RATE_BURST | 否 | 200 | 突发容量 |
| MNEMO_PROVISION_RATE_PER_MINUTE | 否 | 3 | 每个源 IP 每分钟创建租户的请求数，按服务进程独立计算；须为正的有限值 |
| MNEMO_PROVISION_RATE_BURST | 否 | 2 | 创建租户的突发容量；须为正数 |
| MNEMO_UPLOAD_DIR | 否 | ./uploads | 存放上传文件的目录 |
| MNEMO_WORKER_CONCURRENCY | 否 | 5 | 异步上传入库 worker 的并行度 |
| MNEMO_UTM_ENABLED | 否 | false | 开启 UTM 活动跟踪。开启后，创建租户请求里的 utm_ 查询参数会写入控制面数据库。要求 tenant_utm 表已存在 |
| MNEMO_ENV | 否 | development | 部署环境。控制默认 CORS 来源集合（生产环境为 https://mem9.ai；开发环境为 https://mem9.ai,http://localhost:4321,http://127.0.0.1:4321）。也可通过 APP_ENV 设置 |
| MNEMO_CORS_ALLOWED_ORIGINS | 否 | 生产环境为 https://mem9.ai；开发环境为 https://mem9.ai,http://localhost:4321,http://127.0.0.1:4321 | 允许的 CORS 来源，逗号分隔。覆盖基于 MNEMO_ENV 的默认值 |

API key 最长 128 字节，只能包含可打印 ASCII 字符，且中间不能有空白。限流器把 key 指纹存在共享 map 里，最多 100,000 个 IP/key 桶。达到容量上限后，需要新桶的请求会收到 429，直到清理掉过期条目；已有桶仍保持各自的限流。请求 header 预算为 16 KiB。JSON body 限制 1 MiB（超出返回 413）；multipart 导入保留单独的 50 MiB 限制。

嵌入与入库

要在 TiDB Cloud Starter（AWS）上使用内置多语言嵌入，配置： bash
export MNEMO_EMBED_AUTO_MODEL=tidbcloud_free/cohere/embed-multilingual-v3
export MNEMO_EMBED_AUTO_DIMS=1024

新建的记忆表和会话表使用 Cohere 的 search_document 输入类型，搜索时通过 TiDB 的 input_type@search 选项使用 search_query。该模型输入上限为 512 token / 2,048 字符；超长输入会返回错误，而不是悄悄截断已存储的事实。已有的生成列保持原模型；要对比模型请用新的 Space，或者显式迁移/重新嵌入已有表。VEC_EMBED_COSINE_DISTANCE 跟随每列的已存储的模型/选项，所以改动这项设置不会重新嵌入旧的 Space。
参见 TiDB Cohere Auto Embedding。

| 变量 | 必填 | 默认值 | 说明 |
| MNEMO_EMBED_AUTO_MODEL | 否 | — | TiDB/db9 EMBED_TEXT() 模型名。设置后优先于客户端嵌入 |
| MNEMO_EMBED_AUTO_DIMS | 否 | 1024 | MNEMO_EMBED_AUTO_MODEL 的向量维度 |
| MNEMO_EMBED_API_KEY | 否 | — | 客户端嵌入服务商的 API key。设置 MNEMO_EMBED_BASE_URL 后，本地 OpenAI 兼容端点可不填 |
| MNEMO_EMBED_BASE_URL | 否 | 启用客户端嵌入时为 https://api.openai.com/v1 | 自定义 OpenAI 兼容嵌入端点 |
| MNEMO_EMBED_MODEL | 否 | text-embedding-3-small | 客户端嵌入模型名 |
| MNEMO_EMBED_DIMS | 否 | 1536 | 客户端嵌入向量维度 |
| MNEMO_LLM_API_KEY | 否 | — | LLM 服务商 API key。不设置时，智能写入回退到原始写入行为 |
| MNEMO_LLM_BASE_URL | 否 | 启用 LLM 写入时为 https://api.openai.com/v1 | 自定义 OpenAI 兼容对话端点 |
| MNEMO_LLM_MODEL | 否 | gpt-4o-mini | 智能写入使用的 LLM 模型 |
| MNEMO_LLM_TEMPERATURE | 否 | 0.1 | 智能写入使用的 LLM temperature |
| MNEMO_INGEST_MODE | 否 | smart | 写入模式：smart 或 raw |
| MNEMO_FACT_EXTRACTION_INCLUDE_ASSISTANT | 否 | false | 智能写入时，是否提取 assistant 轮次中陈述的持久事实；system 和 tool 轮次仍排除在外 |
| MNEMO_DISABLE_SESSION_SAVE | 否 | false | 消息写入时不再持久化原始会话行，但仍会提取并核对事实 |
| MNEMO_FTS_ENABLED | 否 | false | 启用 TiDB 全文搜索路径。只在支持 TiDB FTS 的集群上设置 |

搜索来源轮次

MEM9_SOURCE_TURN_* 变量控制搜索结果附带多少来源轮次对话，作为上下文装饰。

| 变量 | 必填 | 默认值 | 说明 |
| MEM9_SOURCE_TURN_MIN_SCORE | 否 | 2 | 来源轮次进入搜索结果装饰所需的最低词频相关性分数 |
| MEM9_SOURCE_TURN_PER_MEMORY_LIMIT | 否 | 2 | 搜索结果中单条记忆最多附带的来源轮次数 |
| MEM9_SOURCE_TURN_TOTAL_LIMIT | 否 | 12 | 单次搜索响应中所有记忆合计最多附带的来源轮次数 |

Space Chain 召回

| 变量 | 必填 | 默认值 | 说明 |
| MNEMO_CHAIN_RECALL_STOP_SCORE | 否 | 0.8 | 仅当符合条件的查询最高归一化置信度达到或超过此阈值时，才停止查询后续 Space Chain 节点。原始搜索的 score 值不会触发链式停止。取值必须在 0 到 1 之间 |
| MNEMO_RECALL_REQUEST_TIMEOUT | 否 | 1m | Recall 请求总预算，由服务端掌控，包含响应组装与写入耗时 |
| MNEMO_RECALL_RESPONSE_RESERVE | 否 | 5s | 在 Recall 请求预算内为响应组装与写入预留的时间；必须短于 MNEMO_RECALL_REQUEST_TIMEOUT |

Space Chain 创建门禁

默认情况下，只要能连上服务端，任何人都能创建 Space Chain。创建门禁让运维人员可以为这一个请求 POST /v1alpha2/space-chains 要求共享密钥，也就是创建密钥。门禁默认关闭。关闭期间不检查 Authorization 头，行为没有任何变化。

| 变量 | 必填 | 默认值 | 说明 |
| MNEMO_SPACE_CHAIN_CREATE_SECRET_REQUIRED | 否 | false | 打开创建门禁。接受常见的布尔写法，如 true、false、1、0；首尾空白忽略，空值表示关闭。其他任何值都会让服务端启动失败，这样拼写错误不会让门禁悄悄保持关闭 |
| MNEMO_SPACE_CHAIN_CREATE_SECRET | 门禁打开时必填 | — | 创建密钥。首尾空白忽略。门禁打开而此项为空时，服务端拒绝启动。请把它放进密钥存储；它绝不会写入日志、错误信息或响应 |

门禁打开后，POST /v1alpha2/space-chains 必须携带 Authorization: Bearer <create secret>。请求没有凭证或凭证错误都会得到 401，且不会创建任何东西；两种情况返回结果相同。检查在读取请求体之前执行。只有这一条路由受影响：其他所有端点，包括使用返回的 chain_ 密钥的那些，行为都和以前一样；创建成功时返回 Space Chain Management 一节描述的响应。

自动开通与池化

| 变量 | 必填 | 默认值 | 说明 |
| MNEMO_TIDB_ZERO_ENABLED | 否 | true | 为 tidb 后端启用 TiDB Zero 自动开通。启用后，优先级高于 TiDB Cloud Pool 开通 |
| MNEMO_TIDB_ZERO_API_URL | 否 | https://zero.tidbapi.com/v1alpha1 | TiDB Zero API 基础 URL |
| MNEMO_TIDBCLOUD_API_URL | 否 | https://serverless.tidbapi.com | TiDB Cloud Pool API 基础 URL |
| MNEMO_TIDBCLOUD_POOL_ID | 否 | 2 | 用于接管集群的 TiDB Cloud Pool ID |
| MNEMO_TIDBCLOUD_API_KEY | 否 | — | TiDB Cloud Pool API 密钥。仅在 MNEMO_TIDB_ZERO_ENABLED=false、MNEMO_DB_BACKEND=tidb 且需要池接管时使用 |
| MNEMO_TIDBCLOUD_API_SECRET | 否 | — | 用于 digest 认证的 TiDB Cloud Pool API 密钥。使用条件同 MNEMO_TIDBCLOUD_API_KEY |
| MNEMO_TIDBCLOUD_PREFER_PRIVATELINK | 否 | false | 在 Pool 开通时优先使用 TiDB Cloud 私有端点，前提是下方已配置其 AWS PrivateLink 服务名 |
| MNEMO_TIDBCLOUD_PRIVATELINK_SERVICE_NAMES | 否 | — | 逗号分隔的 AWS PrivateLink 服务名，mem9-server 可访问这些服务。如果返回的服务名不在其中，开通流程回退到公共端点 |
| MNEMO_TENANT_POOL_MAX_IDLE | 否 | 5 | 进程内租户池保留的最大空闲租户数据库连接数 |
| MNEMO_TENANT_POOL_MAX_OPEN | 否 | 10 | 每个租户数据库句柄的最大打开连接数 |
| MNEMO_TENANT_POOL_CONNECT_TIMEOUT | 否 | 3s | 租户池冷连接 ping/open 尝试的超时时间 |
| MNEMO_TENANT_POOL_IDLE_TIMEOUT | 否 | 10m | 租户数据库句柄的空闲超时时间 |
| MNEMO_TENANT_POOL_TOTAL_LIMIT | 否 | 200 | 整个进程允许的租户数据库句柄总数 |
| MNEMO_CLUSTER_BLACKLIST | 否 | — | 逗号分隔的 TiDB 集群 ID，这些集群的 spend-limit 错误应转换为 HTTP 429，而不是 503 |

自动 Spend Limit

这些变量控制 TiDB Cloud 集群触达上限后的自动 spend-limit 提升。该功能会逐步提高限额，最高到 MNEMO_AUTO_SPEND_LIMIT_MAX，每次递增之间有可配置的冷却时间。

| 变量 | 必填 | 默认值 | 说明 |
| MNEMO_AUTO_SPEND_LIMIT_ENABLED | 否 | false | 为 TiDB Cloud 集群启用自动 spend-limit 提升。需要有效的 MNEMO_TIDBCLOUD_API_KEY 和 MNEMO_TIDBCLOUD_API_SECRET |
| MNEMO_AUTO_SPEND_LIMIT_INCREMENT | 否 | 500 | 每步提升 spend limit 的金额（单位 USD 分：500 = $5.00） |
| MNEMO_AUTO_SPEND_LIMIT_MAX | 否 | 10000 | 允许的最大 spend limit（单位 USD 分：10000 = $100.00）。必须大于递增量 |
| MNEMO_AUTO_SPEND_LIMIT_COOLDOWN | 否 | 1h | 同一集群连续两次 spend-limit 提升之间的最短时间 |

计量

这些变量配置旧版服务端 API 计量写入器。它为成功的 recall 和 ingest 操作发出 mem9-api 事件，与运行时用量配额计量相互独立。

计量位置配置为单个目标 URL。支持的 scheme 有：

- s3://<bucket>/<prefix>/，用于写入 S3 的压缩 JSON 批次
- http://... 或 https://...，用于 JSON 批次 webhook

| 变量 | 必填 | 默认值 | 说明 |
| MNEMO_METERING_ENABLED | 否 | false | 启用计量写入器。为 false 时，写入器为空操作 |
| MNEMO_METERING_URL | 否 | — | 计量目标 URL。支持的形式：s3://<bucket>/<prefix>/、http://... 或 https://...。为空时，即使 MNEMO_METERING_ENABLED=true，写入器也保持禁用 |
| MNEMO_METERING_FLUSH_INTERVAL | 否 | 10s | 计量写入器的内存批次刷新间隔 |

运行时用量配额与计量运行时用量默认关闭。开启后，服务器会在记忆召回/写入操作前预留配额，操作失败后释放预留，操作成功后提交预留，并向运行时用量服务发送控制台计量事件。这条路径使用 MNEMO_RUNTIME_USAGE_BASE_URL，不使用 MNEMO_METERING_URL。

运行时用量发件箱使用控制面的 runtime_usage_outbox 表，处理待完成的预留终结和计量投递。开启运行时用量后，发件箱默认启用。

预留重试要求响应精确匹配以下之一，且带 details.retryable: true：409 registry_conflict；429 operation_in_progress、429 registry_busy，或带正十进制整数秒 Retry-After 的 429 reservation_concurrency_limited；或 503 unavailable。预留调用总共最多尝试三次。第一次重试从基础延迟到中点之间采样，第二次从中点到最大延迟之间采样。可重试的 429 响应取采样延迟与 Retry-After 中的较大值。fail-closed 处理停止后，可识别或未知的 429 响应仍为 429；耗尽的 409/503 响应、终态 409 operation_conflict 和未知的 409 响应变为 503。

| 变量 | 必填 | 默认值 | 说明 |
| MNEMO_RUNTIME_USAGE_ENABLED | 否 | false | 为记忆召回/写入操作启用运行时用量配额门控和控制台计量 |
| MNEMO_RUNTIME_USAGE_PROVIDER_ID | 否 | — | 运行时状态响应中返回的运行时用量服务商标识。Mem9 官方托管部署设为 mem9-official；自托管部署通常留空，或使用自己的服务商 id。上游对象形式的 providerData 独立返回，由识别该服务商 id 的消费方解释 |
| MNEMO_RUNTIME_USAGE_BASE_URL | 启用时必填 | — | 运行时用量服务基础 URL。必须是 http 或 https；拒绝 query 和 fragment |
| MNEMO_RUNTIME_USAGE_INTERNAL_SECRET | 启用时必填 | — | 内部运行时用量服务调用的 Bearer token |
| MNEMO_RUNTIME_USAGE_TIMEOUT | 否 | 3s | 配额预留和终结请求的超时 |
| MNEMO_RUNTIME_USAGE_RESERVATION_RETRY_BASE_DELAY | 否 | 500ms | 预留重试抖动的下界。可接受范围：300ms 到 1s |
| MNEMO_RUNTIME_USAGE_RESERVATION_RETRY_MAX_DELAY | 否 | 1s | 预留重试抖动的上界。可接受范围：600ms 到 2s；必须大于基础延迟 |
| MNEMO_RUNTIME_USAGE_METERING_TIMEOUT | 否 | 5s | 控制台计量事件投递请求的超时 |
| MNEMO_RUNTIME_USAGE_RESERVATION_TTL | 否 | 30m | 解析进服务器配置，但目前不发送到预留请求；修改它不会改变预留生命周期 |
| MNEMO_RUNTIME_USAGE_OPERATION_TTL | 否 | 30m | 会解析进服务端配置，但目前不用它让运行时用量 outbox 行过期；改这个值不影响 outbox 的生命周期 |
| MNEMO_RUNTIME_USAGE_FAIL_OPEN | 否 | false | 配额预留失败、且运行时用量服务返回可重试错误时，允许继续操作。配额拒绝和操作冲突仍然按失败关闭处理 |

| MNEMO_RUNTIME_USAGE_OUTBOX_ENABLED | No | same as MNEMO_RUNTIME_USAGE_ENABLED | Persist pending reservation and metering steps for retry. If explicitly set to false while runtime usage is enabled, MNEMO_RUNTIME_USAGE_FAIL_OPEN must be true |
| MNEMO_RUNTIME_USAGE_NOTICE_TIMEOUT | No | 1s | Timeout for best-effort runtime-state lookups used only by success response notices |
| MNEMO_RUNTIME_USAGE_NOTICE_CACHE_ENABLED | No | true | Enable API-key-scoped caching for success response runtime-state notices |
| MNEMO_RUNTIME_USAGE_NOTICE_CACHE_TTL | No | 30s | Fresh TTL for success response runtime-state notice cache entries |
| MNEMO_RUNTIME_USAGE_NOTICE_STALE_TTL | No | 2m | Maximum stale-cache age used for success notices when the state provider is unavailable |

Security And Debugging

| Variable | Required | Default | Description |
| MNEMO_ENCRYPT_TYPE | No | plain | Encryption type for tenant DB passwords: plain, md5, or kms. One-time deployment decision. |
| MNEMO_ENCRYPT_KEY | No | — | Encryption key for md5 or KMS key ID for kms. Required when MNEMO_ENCRYPT_TYPE is not plain |
| MNEMO_DEBUG_LLM | No | false | Log raw LLM responses for debugging parse errors. Use only in dev/test because responses may contain user data |

AWS KMS Environment

These are only relevant when MNEMO_ENCRYPT_TYPE=kms. The server uses the AWS SDK default config chain; the common environment-based inputs referenced in code are:

| Variable | Required | Default | Description |
| AWS_ACCESS_KEY_ID | No | — | AWS access key ID for KMS auth when using environment-based AWS credentials |
| AWS_SECRET_ACCESS_KEY | No | — | AWS secret access key for KMS auth when using environment-based AWS credentials |
| AWS_REGION | No | — | AWS region used to create the KMS client |

Test-Only

| Variable | Required | Default | Description |
| MNEMO_TEST_DSN | No | Falls back to MNEMO_DSN | Integration-test DSN used by server repository tests |

Repository Map

| Path | Role |
| server/ | Core Go REST API and source of truth for spaces, memories, search, ingest, and tenant provisioning |
| cli/ | Standalone Go CLI for exercising mem9 API and ingest flows |
| openclaw-plugin/ | OpenClaw memory plugin |
| opencode-plugin/ | OpenCode plugin |
| claude-plugin/ | Claude Code hooks and skills integration |
| codex-plugin/ | Codex marketplace plugin and managed hooks |
| dsh-plugin/ | DeepSeek Harness DSH/Cordis bundle |
| site/ | Public mem9.ai site and published onboarding assets |
| dashboard/ | Dashboard product frontend and supporting product docs |
| benchmark/ | Benchmark harnesses and datasets for mem9 evaluation |
| e2e/ | Live end-to-end scripts against a running mem9 server |
| docs/ | Architecture notes, design docs, and feature specs |

Related Repositories

| Repository | What it owns | When to look there |
| mem9 | Core Go API server, agent plugins, CLI, site, dashboard frontend, benchmark harnesses, and docs | You are working on the shared memory server, plugin integrations, or the main product docs |
| mem9-node | Dashboard analysis backend, async jobs, and worker flows | A dashboard feature depends on backend APIs, background jobs, or analysis pipelines |
| mem9-hermes-plugin | Hermes Agent plugin packaging, setup flow, and Hermes-specific docs | You are changing Hermes installation, activation, or runtime-specific behavior |
| mem9-dify-plugin | Dify tool plugin, memory tools, authorization modes, and Dify-specific docs | You are changing Dify Agent app, Workflow app, or multi-space plugin behavior |

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

Apache-2.0

Built on TiDB Cloud Starter for shared memory, vector search, and managed cloud provisioning.