# https://github.com/MemoriLabs/Memori 项目说明书

生成时间：2026-06-22 20:17:16 UTC

## 目录

- [Memori Overview & System Architecture](#page-overview)
- [Python & TypeScript SDKs and Rust Core](#page-sdks)
- [BYODB Storage Layer & Local OpenAI-Compatible Endpoints](#page-storage)
- [LLM Provider Adapters, Framework Integrations & MCP](#page-integrations)

<a id='page-overview'></a>

## Memori Overview & System Architecture

### 相关页面

相关主题：[Python & TypeScript SDKs and Rust Core](#page-sdks), [BYODB Storage Layer & Local OpenAI-Compatible Endpoints](#page-storage)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/MemoriLabs/Memori/blob/main/README.md)
- [integrations/hermes/README.md](https://github.com/MemoriLabs/Memori/blob/main/integrations/hermes/README.md)
- [integrations/openclaw/README.md](https://github.com/MemoriLabs/Memori/blob/main/integrations/openclaw/README.md)
- [integrations/claude-code/README.md](https://github.com/MemoriLabs/Memori/blob/main/integrations/claude-code/README.md)
- [memori-ts/README.md](https://github.com/MemoriLabs/Memori/blob/main/memori-ts/README.md)
- [integrations/hermes/src/memori_hermes/client.py](https://github.com/MemoriLabs/Memori/blob/main/integrations/hermes/src/memori_hermes/client.py)
- [integrations/hermes/src/memori_hermes/tools.py](https://github.com/MemoriLabs/Memori/blob/main/integrations/hermes/src/memori_hermes/tools.py)
- [memori-ts/src/types/api.ts](https://github.com/MemoriLabs/Memori/blob/main/memori-ts/src/types/api.ts)
- [memori-ts/src/types/integrations.ts](https://github.com/MemoriLabs/Memori/blob/main/memori-ts/src/types/integrations.ts)
- [integrations/openclaw/src/types.ts](https://github.com/MemoriLabs/Memori/blob/main/integrations/openclaw/src/types.ts)
</details>

# Memori 概述与系统架构

## 1. 项目定位与设计理念

Memori 是一个面向 AI 代理（agent）的结构化长期记忆层，官方将其核心价值主张总结为 "Memory from what agents do, not just what they say"。这意味着 Memori 不仅记录对话文本，更强调捕获代理在执行过程中的工具调用、决策、结果与失败，把"代理做了什么"作为一等公民写入长期记忆。资料来源：[README.md:1-40]()

在架构立场方面，Memori 自描述为"LLM 无关、数据存储无关、框架无关"，并主张以"对现有架构无侵入"的方式接入已有系统。资料来源：[README.md:5-20]()
围绕该定位，社区多次提出扩展诉求，例如支持本地 OpenAI 兼容端点（Ollama / vLLM / llama.cpp / koboldcpp），以便在无外部 LLM 服务的情况下仍能使用 Memori。资料来源：[integrations/openclaw/README.md:1-30]()

## 2. 系统总体架构

Memori 的多个集成共享同一套"双系统并行"架构，可统一理解为一条"写入—存储—召回"的数据流：

1. **Advanced Augmentation（高级增强）**：在每次交互后，Memori 将原始会话数据异步转换为结构化、可复用的记忆单元，捕获代理动作、推理、工具使用、回复、纠正与失败，并生成向量嵌入以支持语义检索。资料来源：[integrations/openclaw/README.md:60-100]()
2. **Agent-Controlled Intelligent Recall（代理控制的智能召回）**：通过显式工具（如 `memori_recall`、`memori_recall_summary`、`memori_compaction`、`memori_feedback`、`memori_quota`）让代理按需获取结构化上下文，避免把长历史一股脑塞回 prompt。资料来源：[integrations/hermes/src/memori_hermes/tools.py:1-60]()

```mermaid
flowchart LR
    A[代理运行时<br/>Agent Runtime] -->|执行轨迹 + 对话| B(Advanced Augmentation<br/>异步结构化)
    B --> C[(Memori 记忆存储<br/>结构化事实 + 嵌入)]
    A -->|显式工具调用| D[Agent-Controlled Recall<br/>memori_recall / _summary / _compaction]
    D -->|作用域过滤| C
    C -->|按实体/项目/会话返回| D
    D -->|上下文注入| A
```

## 3. 核心数据模型与作用域

为防止记忆在不同用户、项目之间相互污染，Memori 引入了一组**作用域标识符**对记忆做严格切片：

- `entity_id`：用户、代理或系统的唯一标识，是写入与检索请求的必备字段。资料来源：[memori-ts/src/types/integrations.ts:1-80]()、资料来源：[memori-ts/src/types/api.ts:1-40]()
- `process_id`：可选的进程/工作流标识，用于在同一 `entity` 下区分多个并行流程。资料来源：[memori-ts/src/types/integrations.ts:1-80]()
- `project_id`：项目或工作区粒度的作用域，在 OpenClaw 插件配置中是必填项。资料来源：[integrations/openclaw/src/types.ts:1-20]()
- `session_id`：单次会话标识，可作为 `memori_recall` 的可选过滤项。资料来源：[integrations/hermes/src/memori_hermes/tools.py:1-60]()

在 API 形态上，TypeScript SDK 将上述字段组装为 `AugmentationInput`，作为 Rust 核心 Augmentation Engine 的严格入参；检索侧则暴露 `RetrievalRequest`，由 `entity_id` 与 `query_text` 共同决定返回结果。资料来源：[memori-ts/src/types/integrations.ts:1-80]()、资料来源：[memori-ts/src/types/api.ts:1-40]()

## 4. 集成生态与故障容错

Memori 通过多语言 SDK 与多种代理框架解耦，目前主线集成包括：

- **Python SDK**：通过 `pip install memori` 安装，被 Hermes 客户端显式导入并由 `MemoriAgentClient` 包装。资料来源：[integrations/hermes/src/memori_hermes/client.py:1-40]()
- **TypeScript SDK**：`@memorilabs/memori`，提供 `IntegrationMetadata` 等类型用于 Augmentation Engine 的遥测与元数据标注。资料来源：[memori-ts/README.md:1-30]()、资料来源：[memori-ts/src/types/integrations.ts:1-80]()
- **OpenClaw 插件**：`@memorilabs/openclaw-memori`，以 drop-in 方式提供"Advanced Augmentation + Intelligent Recall"。资料来源：[integrations/openclaw/README.md:1-60]()
- **Hermes Agent 记忆提供方**：`hermes-memori` 注册为 Hermes 的 `memory.provider`，与 `MEMORY.md` / `USER.md` 并存而不互相覆盖。资料来源：[integrations/hermes/README.md:1-80]()
- **Claude Code 技能**：以 Bun 实现的本地 CLI 形式存在，将 `SKILL.md` + `index.ts` 部署到 `.claude/skills/memori/` 即可启用。资料来源：[integrations/claude-code/README.md:1-20]()

需要特别强调的是，Memori 的各集成普遍采用 **fail-soft（软失败）** 设计：当 Memori Cloud 不可达或调用失败时，仅记录日志而不阻断代理对用户的回复，使记忆层成为可降级的增强组件而非单点故障。资料来源：[integrations/hermes/README.md:80-110]()

## 另请参阅

- [OpenClaw 集成概览](openclaw-overview.md)
- [Hermes 记忆提供方 API](hermes-provider.md)
- [TypeScript SDK 类型参考](memori-ts-types.md)

---

<a id='page-sdks'></a>

## Python & TypeScript SDKs and Rust Core

### 相关页面

相关主题：[Memori Overview & System Architecture](#page-overview), [LLM Provider Adapters, Framework Integrations & MCP](#page-integrations)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [core/README.md](https://github.com/MemoriLabs/Memori/blob/main/core/README.md)
- [core/src/lib.rs](https://github.com/MemoriLabs/Memori/blob/main/core/src/lib.rs)
- [core/src/runtime/config.rs](https://github.com/MemoriLabs/Memori/blob/main/core/src/runtime/config.rs)
- [core/src/storage/models.rs](https://github.com/MemoriLabs/Memori/blob/main/core/src/storage/models.rs)
- [core/src/augmentation/pipeline.rs](https://github.com/MemoriLabs/Memori/blob/main/core/src/augmentation/pipeline.rs)
- [core/bindings/python/src/lib.rs](https://github.com/MemoriLabs/Memori/blob/main/core/bindings/python/src/lib.rs)
- [core/bindings/node/src/lib.rs](https://github.com/MemoriLabs/Memori/blob/main/core/bindings/node/src/lib.rs)
- [memori-ts/package.json](https://github.com/MemoriLabs/Memori/blob/main/memori-ts/package.json)
- [memori-ts/src/types/api.ts](https://github.com/MemoriLabs/Memori/blob/main/memori-ts/src/types/api.ts)
- [memori-ts/src/types/integrations.ts](https://github.com/MemoriLabs/Memori/blob/main/memori-ts/src/types/integrations.ts)
- [integrations/hermes/src/memori_hermes/tools.py](https://github.com/MemoriLabs/Memori/blob/main/integrations/hermes/src/memori_hermes/tools.py)
- [integrations/openclaw/package.json](https://github.com/MemoriLabs/Memori/blob/main/integrations/openclaw/package.json)
- [integrations/openclaw/src/tools/memori-recall.ts](https://github.com/MemoriLabs/Memori/blob/main/integrations/openclaw/src/tools/memori-recall.ts)
- [integrations/claude-code/README.md](https://github.com/MemoriLabs/Memori/blob/main/integrations/claude-code/README.md)
</details>

# Python 与 TypeScript SDK 以及 Rust Core

## 总体定位与分层架构

Memori 项目由三个紧密协作的层级组成：底层的 Rust 核心（`engine-orchestrator`）、中间的 Python / TypeScript SDK、以及上层面向不同 LLM 框架与 CLI 的集成包（Hermes、OpenClaw、Claude Code 等）。最新发行版本为 **3.3.6**（参见 PR #561、#562、#563），其中 `fastembed` 已被作为 Rust 后端独家使用 资料来源：[memori-ts/package.json:1-60]()。

核心代码集中在 `core/` 目录，其官方文档明确说明：`engine-orchestrator` 负责同步嵌入生成、有界异步工作池（postprocess 与 augmentation），以及在宿主提供的 `StorageBridge` 上完成的同步检索流程 资料来源：[core/README.md:1-35]()。这种职责划分使得 Rust 核心成为"无状态业务逻辑"的承载者，而所有 IO、持久化、跨语言交互都委托给宿主语言（Python 或 Node）。

依赖方向被严格约束为单向：

```
engine-orchestrator  →  bindings/{python,node}  →  Memori SDKs
```

绑定层只允许调用 `engine-orchestrator` 的公共 API，不可复用其内部模块 资料来源：[core/README.md:11-18]()。

## Rust Core：引擎核心

### 模块组成

Rust 核心暴露的关键模块包括 `augmentation`、`embeddings`、`retrieval`、`runtime`、`storage`、`network`、`search` 等 资料来源：[core/src/lib.rs:1-50]()。`EngineOrchestrator` 是顶层入口，持有：

- 同步嵌入管道（基于 `fastembed`）；
- 两个有界异步工作运行时：`WorkerRuntime<PostprocessJob>` 与 `WorkerRuntime<AugmentationJob>`；
- 可选的宿主提供的 [`storage::StorageBridge`]，检索流水线通过它进行读写。

### 工作运行时配置

`RuntimeConfig` 默认配置为 `queue_capacity=256`、`max_concurrency=32`，并使用 `ShutdownPolicy::Drain` 策略，保证已入队与正在执行的任务在停止前完成 资料来源：[core/src/runtime/config.rs:1-60]()。这一默认值适用于大多数生产部署；当宿主语言绑定层在 30 秒内未响应回调时，`PythonStorageBridge` 会主动超时 资料来源：[core/bindings/python/src/lib.rs:1-60]()。

### 检索与扩展流程

检索路径接收 `RetrievalRequest`（含 `entity_id`、`query_text`、`dense_limit`、`limit`），由 Rust 核心执行稠密余弦相似度与 BM25 重排序 资料来源：[memori-ts/src/types/api.ts:1-30]()。写入侧则通过 `WriteBatch` / `WriteOp` 实现 op 类型（如 `entity_fact.create`、`upsert_fact`），并在 `attach_entity_fact_embeddings` 中跳过全零向量行，确保嵌入一致性 资料来源：[core/src/augmentation/pipeline.rs:1-60]()。

```mermaid
flowchart LR
    A[上层 SDK / 集成] --> B[Python PyO3 绑定]
    A --> C[Node napi-rs 绑定]
    B --> D[engine-orchestrator]
    C --> D
    D --> E[fastembed 嵌入]
    D --> F[WorkerRuntime Postprocess]
    D --> G[WorkerRuntime Augmentation]
    D --> H[StorageBridge 宿主存储]
    H --> I[(SQLite / Postgres / MySQL<br/>CockroachDB / Cloud)]
```

## Python 与 Node 绑定

两个绑定都被设计为"薄适配器"：Python 端使用 PyO3，Node 端使用 napi-rs 资料来源：[core/bindings/python/src/lib.rs:1-30]() 与 [core/bindings/node/src/lib.rs:1-10]()。它们只承担 JSON 序列化、回调路由、超时控制等职责，**不**复制任何业务逻辑。

- Python 绑定暴露 `MemoriEngine`，并将宿主回调（`fetch_embeddings`、`fetch_facts_by_ids`、`write_batch`）封装为 `PythonStorageBridge`，调用间隔通过 `Mutex<mpsc::Receiver>` 同步化。
- Node 绑定通过 `mod engine; mod bridge; mod types;` 模块拆分，由 `MemoriEngine` 作为对外主类，并重新导出 NAPI 类型以便自动生成 `.d.ts`。

TypeScript SDK 自身在 `memori-ts/` 下编译为 ESM 包，`main` 指向 `dist/index.js`，并暴露 `./integrations` 子路径以加载框架插件 资料来源：[memori-ts/package.json:1-60]()。

## 上层集成：Hermes、OpenClaw、Claude Code

### Hermes（Python）

Hermes 集成声明了一组 LLM 工具 schema，包括 `memori_recall`、`memori_recall_summary`、`memori_compaction`、`memori_feedback`、`memori_quota`、`memori_signup` 等。`memori_recall` 接受自然语言查询、ISO 8601 时间区间、`projectId`、`sessionId`、可选的 `signal` 与 `source` 过滤项 资料来源：[integrations/hermes/src/memori_hermes/tools.py:1-60]()。系统提示中明确要求：当 `sessionId` 已提供时必须同时给出 `projectId`，避免跨项目数据泄露。

### OpenClaw（Node）

OpenClaw 包为 Node ≥ 22 设计，依赖 `@memorilabs/axon ^0.1.5`，并通过 `openclaw.extensions` 字段声明扩展入口 资料来源：[integrations/openclaw/package.json:1-60]()。其 `memori-recall` 工具执行严格的入参校验：`sessionId` 必须与 `projectId` 同时出现；`source` 与 `signal` 必须成对提供或同时省略，避免出现不完整的过滤条件 资料来源：[integrations/openclaw/src/tools/memori-recall.ts:1-60]()。

### Claude Code

Claude Code 集成是一个 Bash 调用的本地 Skill（`SKILL.md` + `index.ts`），通过 Bun 运行时调用 Memori Cloud 完成每轮 recall 与 record 资料来源：[integrations/claude-code/README.md:1-40]()。该集成是参考实现，只需把两个文件复制到 `.claude/skills/memori/` 即可生效。

## 社区关注点与版本说明

社区多次请求支持**本地或自定义 OpenAI 兼容端点**（Ollama、vLLM、llama.cpp、koboldcpp 等），相关讨论集中在 Issue #250 与 #40。这意味着 SDK 需要在 `OpenAIIntegration` 默认 `api.openai.com` 之外，允许通过配置覆盖 `base_url`（当前 TypeScript SDK 已为此预留 `@memorilabs/axon` 依赖抽象）。

最新 3.3.6 版本（PR #561、#562、#563）进一步强化了 Rust 端的 `fastembed` 后端独占性，并修复了 MySQL datetime 类型问题，提示用户在升级后注意：

1. 旧的 Python/Node 二进制可能需要重新构建；
2. MySQL 表结构应核对 `datetime` 列是否需要迁移；
3. 使用 `cargo check-all && cargo test-all` 在本地验证 engine-orchestrator 是否兼容新版本 资料来源：[core/README.md:25-35]()。

## See Also

- Memori Cloud API 客户端配置：[memori-ts/src/types/api.ts]()
- 集成输入负载定义：[memori-ts/src/types/integrations.ts]()
- 存储桥接数据模型：[core/src/storage/models.rs]()
- 嵌入批处理与对齐：[core/src/augmentation/pipeline.rs]()

---

<a id='page-storage'></a>

## BYODB Storage Layer & Local OpenAI-Compatible Endpoints

### 相关页面

相关主题：[Memori Overview & System Architecture](#page-overview), [Python & TypeScript SDKs and Rust Core](#page-sdks)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/MemoriLabs/Memori/blob/main/README.md)
- [memori-ts/README.md](https://github.com/MemoriLabs/Memori/blob/main/memori-ts/README.md)
- [core/src/storage/models.rs](https://github.com/MemoriLabs/Memori/blob/main/core/src/storage/models.rs)
- [core/src/embeddings/mod.rs](https://github.com/MemoriLabs/Memori/blob/main/core/src/embeddings/mod.rs)
- [core/src/retrieval/mod.rs](https://github.com/MemoriLabs/Memori/blob/main/core/src/retrieval/mod.rs)
- [core/src/augmentation/mod.rs](https://github.com/MemoriLabs/Memori/blob/main/core/src/augmentation/mod.rs)
- [core/src/runtime/config.rs](https://github.com/MemoriLabs/Memori/blob/main/core/src/runtime/config.rs)
- [core/src/runtime/worker.rs](https://github.com/MemoriLabs/Memori/blob/main/core/src/runtime/worker.rs)
- [integrations/hermes/src/memori_hermes/client.py](https://github.com/MemoriLabs/Memori/blob/main/integrations/hermes/src/memori_hermes/client.py)
- [integrations/hermes/src/memori_hermes/tools.py](https://github.com/MemoriLabs/Memori/blob/main/integrations/hermes/src/memori_hermes/tools.py)
- [integrations/openclaw/README.md](https://github.com/MemoriLabs/Memori/blob/main/integrations/openclaw/README.md)
</details>

# BYODB 存储层与本地 OpenAI 兼容端点

## 概览与定位

Memori 是一个面向 LLM 代理的结构化、长期记忆系统，其核心定位是 **"LLM、数据存储与框架均无关"**——可以接入已有的软件与基础设施体系 [README.md](https://github.com/MemoriLabs/Memori/blob/main/README.md)。在这一原则下，项目提供两条互补的部署路径：**Memori Cloud**（零配置托管）与 **BYODB（Bring Your Own Database，自带数据库）**；同时支持多种 LLM 提供方，包括 OpenAI、Anthropic、Google Gemini，并通过拦截器（interceptor）模式实现接入。

社区的两次高互动议题（[#40](https://github.com/MemoriLabs/Memori/issues/40) 与 [#250](https://github.com/MemoriLabs/Memori/issues/250)）均聚焦于"本地与自定义 OpenAI 兼容端点"——例如 Ollama、vLLM、llama.cpp、koboldcpp——这与 BYODB 一起构成开发者最关心的两类自托管能力。

## BYODB 存储架构

BYODB 模式允许开发者将 Memori 直接部署到自有数据库上。根据 [memori-ts/README.md](https://github.com/MemoriLabs/Memori/blob/main/memori-ts/README.md)，**SQLite、PostgreSQL 与 MySQL 均为受支持目标**；开发者可将任意 ORM 的底层连接池直接传入，开箱即用。

在 Rust 核心层，存储抽象以请求/响应模型组织。`core/src/storage/models.rs` 暴露了 `FetchEmbeddingsRequest` 与 `FetchFactsByIdsRequest` 等结构体，前者按 `entity_id` 拉取指定数量的向量，后者按事实 ID 列表批量取回事实记录；同时定义了 `HostStorageError`，以 `(code, message)` 的形式将宿主存储错误结构化向上层传递 [core/src/storage/models.rs](https://github.com/MemoriLabs/Memori/blob/main/core/src/storage/models.rs)。

嵌入生成由 `fastembed` 后端提供 [core/src/embeddings/mod.rs](https://github.com/MemoriLabs/Memori/blob/main/core/src/embeddings/mod.rs)。在 3.3.6 版本中，Rust 的 `fastembed` 成为**唯一**的嵌入后端（见 Release 3.3.6 变更日志），并修复了 MySQL `datetime` 类型相关问题，显著提升了 BYODB 模式下 MySQL 用户的可用性。

写入路径通过 `core/src/augmentation/mod.rs` 的 `run_advanced_augmentation` 完成事实结构化，并经由 `attach_entity_fact_embeddings` 关联嵌入，最终由 `build_write_batch_from_response` 构造写入批次落入宿主数据库 [core/src/augmentation/mod.rs](https://github.com/MemoriLabs/Memori/blob/main/core/src/augmentation/mod.rs)。

读取路径位于 `core/src/retrieval/mod.rs`，由 `pipeline::run_retrieval` 执行检索，再经 `format_recall_output` 序列化为可注入提示的回忆内容 [core/src/retrieval/mod.rs](https://github.com/MemoriLabs/Memori/blob/main/core/src/retrieval/mod.rs)。

## 本地 OpenAI 兼容端点

OpenAI 兼容端点的支持源自社区反复提出的需求（[#40](https://github.com/MemoriLabs/Memori/issues/40) 与 [#250](https://github.com/MemoriLabs/Memori/issues/250)）：开发者希望在同一套记忆系统下使用 Ollama、vLLM、llama.cpp、koboldcpp 等本地推理服务，而不被锁定在 `api.openai.com`。

在 Memori 的设计中，**LLM 提供方通过拦截器解耦**——上层只需把请求/响应轨迹送入记忆管线，不必关心底层是 OpenAI 还是自托管的兼容服务 [README.md](https://github.com/MemoriLabs/Memori/blob/main/README.md)。Hermes 集成展示了这一模式的落地方式：`MemoriAgentClient` 通过 `from memori import Memori` 引入 SDK，并接受 `api_key` 与可选的 `base_url` 参数 [integrations/hermes/src/memori_hermes/client.py](https://github.com/MemoriLabs/Memori/blob/main/integrations/hermes/src/memori_hermes/client.py)。这意味着只要底层 SDK 允许指向自定义端点（如 `http://localhost:11434/v1`），即可在 Hermes 提供器中调用本地 LLM；OpenClaw 集成亦采用相同的插件化注册流程（`openclaw plugins install` 与 `openclaw memori init`）[integrations/openclaw/README.md](https://github.com/MemoriLabs/Memori/blob/main/integrations/openclaw/README.md)。

社区反馈中需要关注的限制是：截至当前仓库内容，**对 OpenAI 兼容端点的官方文档化支持仍处于演进阶段**，官方默认行为以官方 OpenAI API 为准；切换至本地端点时需自行确认所调用的 SDK 或拦截器接受 `base_url` 重写。

## 两套并行系统：增强与回忆

无论使用 Cloud 还是 BYODB，Memori 都运行在两套并行系统上：

1. **Advanced Augmentation（高级增强）**——异步把原始会话转化为结构化记忆单元，捕获代理的工具调用、决策、结果与失败，并生成嵌入用于语义检索 [integrations/openclaw/README.md](https://github.com/MemoriLabs/Memori/blob/main/integrations/openclaw/README.md)。
2. **Agent-Controlled Recall（代理控制回忆）**——以显式工具形式暴露，例如 Hermes 提供器的 `memori_recall` 与 `memori_recall_summary` [integrations/hermes/src/memori_hermes/tools.py](https://github.com/MemoriLabs/Memori/blob/main/integrations/hermes/src/memori_hermes/tools.py)。`SIGNALS`（`commit/discovery/failure/inference/pattern/result/update/verification`）与 `SOURCES`（`constraint/decision/execution/fact/insight/instruction/status/strategy/task`）枚举了可被结构化标签的信号与来源类型。

写入与异步执行由 `WorkerRuntime` 驱动。`RuntimeConfig` 默认 `queue_capacity=256`、`max_concurrency=32`，并通过 `ShutdownPolicy::Drain` 保证已接收任务在关闭前被处理完毕 [core/src/runtime/config.rs](https://github.com/MemoriLabs/Memori/blob/main/core/src/runtime/config.rs)。`worker.rs` 中的 `OutstandingGuard` 在任务被丢弃时递减计数并唤醒等待者，确保 LLM 调用不会因记忆管线阻塞而延迟 [core/src/runtime/worker.rs](https://github.com/MemoriLabs/Memori/blob/main/core/src/runtime/worker.rs)。

```mermaid
flowchart LR
  A[LLM 调用拦截器<br/>OpenAI / 本地兼容端点] --> B[WorkerRuntime<br/>queue=256, drain]
  B --> C[Advanced Augmentation<br/>结构化 + 嵌入 fastembed]
  C --> D[(BYODB:<br/>SQLite / PG / MySQL)]
  D --> E[Retrieval Pipeline]
  E --> F[memori_recall 工具]
  F --> G[提示词注入]
```

## 常见问题与故障排查

- **MySQL 时间类型异常**：3.3.5 → 3.3.6 修复了 `datetime` 类型问题，请升级至 3.3.6。
- **本地端点不生效**：确认所用的 SDK / 拦截器层支持 `base_url` 覆盖；Hermes 客户端的 `MemoriAgentClient.__init__` 显式接受 `base_url` 参数，可作为参考。
- **任务积压/未落库**：`RuntimeConfig::validate()` 要求 `queue_capacity≥1`、`max_concurrency≥1`；配置错误会被构造时拒绝。
- **记忆未被写入**：必须设置归属（attribution），即 `entity_id` 与 `process_id`，否则 Memori 无法为你生成记忆 [memori-ts/README.md](https://github.com/MemoriLabs/Memori/blob/main/memori-ts/README.md)。

## 另请参阅

- [Memori Cloud 文档](https://memorilabs.ai/docs/memori-cloud/)
- [BYODB 完整指南](https://memorilabs.ai/docs/memori-byodb/)
- [Hermes 集成快速上手](https://memorilabs.ai/docs/memori-cloud/hermes/quickstart.mdx)
- [OpenClaw 集成快速上手](https://memorilabs.ai/docs/memori-cloud/openclaw/quickstart.mdx)
- 相关社区议题：#40、#170、#250

---

<a id='page-integrations'></a>

## LLM Provider Adapters, Framework Integrations & MCP

### 相关页面

相关主题：[Python & TypeScript SDKs and Rust Core](#page-sdks), [BYODB Storage Layer & Local OpenAI-Compatible Endpoints](#page-storage)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/MemoriLabs/Memori/blob/main/README.md)
- [memori-ts/README.md](https://github.com/MemoriLabs/Memori/blob/main/memori-ts/README.md)
- [memori-ts/src/types/integrations.ts](https://github.com/MemoriLabs/Memori/blob/main/memori-ts/src/types/integrations.ts)
- [memori-ts/src/types/api.ts](https://github.com/MemoriLabs/Memori/blob/main/memori-ts/src/types/api.ts)
- [integrations/hermes/README.md](https://github.com/MemoriLabs/Memori/blob/main/integrations/hermes/README.md)
- [integrations/hermes/src/memori_hermes/__init__.py](https://github.com/MemoriLabs/Memori/blob/main/integrations/hermes/src/memori_hermes/__init__.py)
- [integrations/hermes/src/memori_hermes/tools.py](https://github.com/MemoriLabs/Memori/blob/main/integrations/hermes/src/memori_hermes/tools.py)
- [integrations/hermes/src/memori_hermes/client.py](https://github.com/MemoriLabs/Memori/blob/main/integrations/hermes/src/memori_hermes/client.py)
- [integrations/hermes/src/memori_hermes/install.py](https://github.com/MemoriLabs/Memori/blob/main/integrations/hermes/src/memori_hermes/install.py)
- [integrations/openclaw/README.md](https://github.com/MemoriLabs/Memori/blob/main/integrations/openclaw/README.md)
- [integrations/openclaw/src/tools/memori-recall.ts](https://github.com/MemoriLabs/Memori/blob/main/integrations/openclaw/src/tools/memori-recall.ts)
- [integrations/openclaw/src/types.ts](https://github.com/MemoriLabs/Memori/blob/main/integrations/openclaw/src/types.ts)
- [integrations/openclaw/package.json](https://github.com/MemoriLabs/Memori/blob/main/integrations/openclaw/package.json)
- [core/src/augmentation/mod.rs](https://github.com/MemoriLabs/Memori/blob/main/core/src/augmentation/mod.rs)
</details>

# LLM Provider Adapters、Framework Integrations 与 MCP

## 概述

Memori 官方定位为 "LLM、data store、framework 都无关 (agnostic) 的可插拔记忆层"：通过 **Adapter（适配器）** 接入上游 LLM 客户端，通过 **Framework Integration（框架集成）** 让 Agent 框架主动使用结构化记忆工具，并通过 **MCP 客户端设置** 把任何兼容 MCP 的 IDE / CLI（如 Cursor、Codex、Warp）变为具备长期记忆能力的客户端。资料来源：[README.md:1-10]()

整个工作流在 Rust 核心的 Augmentation Engine 中汇聚：上游 LLM SDK 完成一次 chat 后被适配器拦截，序列化为 `AugmentationInput`，由 `run_advanced_augmentation` 管道结构化写入与召回。资料来源：[core/src/augmentation/mod.rs:1-15]()

```mermaid
flowchart LR
  A[LLM SDK<br/>OpenAI/Anthropic/...] --> B[Adapter<br/>.llm.register]
  C[Agent Framework<br/>Hermes/OpenClaw] --> D[Integration<br/>memori_recall tool]
  E[MCP Client<br/>Cursor/Codex/Warp] --> F[MEMORI_API_KEY<br/>+ X-Memori-Process-Id]
  B --> G[AugmentationInput]
  D --> G
  F --> G
  G --> H[Rust Core<br/>Augmentation Engine]
  H --> I[(Memori Cloud / Self-hosted DB)]
```

## LLM Provider Adapters

Python 与 TypeScript SDK 都通过 `.llm.register(client)` 把原生 LLM 客户端挂到 Memori 上。README 明确列出的官方支持厂商包括 **Anthropic**；TypeScript 端 Quickstart 默认演示了 OpenAI。资料来源：[README.md:90-110]() [memori-ts/README.md:30-50]()

每次 LLM 交互都需先调用 `attribution(entity_id, process_id)` 建立归属，缺少归属时 Memori 无法生成记忆；会话粒度由 `new_session()` / `set_session()` 控制。资料来源：[README.md:60-80]()

上报到 Rust 核心的 `IntegrationMetadata` 显式记录了 LLM 厂商、模型、SDK 版本与运行框架，例如 `provider: "anthropic"`、`model: "claude-3.5-sonnet"`、`platform: "openclaw"`。资料来源：[memori-ts/src/types/integrations.ts:13-44]()

社区多次反馈（Issue **#250**、**#40**）希望 `OpenAIIntegration` 支持本地 OpenAI 兼容端点（Ollama、vLLM、llama.cpp、koboldcpp），目前默认仍指向 `api.openai.com`，相关讨论仍在追踪中。

## Framework Integrations

仓库在 `integrations/` 下提供两种 Agent 框架的官方集成包，二者共享同一套 `memori_recall` 工具契约。

### Hermes Agent（Python）

- 安装方式：`pip install hermes-memori` 后执行 `hermes-memori install`；路径解析顺序为 `--hermes-home` → Hermes 自带 home resolver → `HERMES_HOME` 环境变量 → Windows `%LOCALAPPDATA%\hermes` → POSIX `~/.hermes`。资料来源：[integrations/hermes/src/memori_hermes/install.py:35-72]()
- 配置方式：运行 `hermes memory setup` 选择 `memori`，或手动把 `MEMORI_API_KEY`、`MEMORI_ENTITY_ID` 写入 `$HERMES_HOME/.env`，可选 `$HERMES_HOME/memori.json` 提供 `entityId` / `projectId`。资料来源：[integrations/hermes/README.md:18-50]()
- `MemoriConfig` 数据类持有 `api_key / entity_id / project_id / process_id / base_url` 五个字段，缺一即抛出配置错误。资料来源：[integrations/hermes/src/memori_hermes/__init__.py:48-55]()

### OpenClaw（TypeScript / Node ≥ 22）

- 前置依赖 OpenClaw `v2026.3.2+`；通过 `openclaw plugins install @memorilabs/openclaw-memori` 安装并 `enable`，再以 `openclaw memori init --api-key … --entity-id … --project-id …` 完成初始化。资料来源：[integrations/openclaw/README.md:13-30]() [integrations/openclaw/package.json:42-50]()
- 集成层将 OpenClaw 事件解析成 `ParsedTurn`（`userMessage / assistantMessage / tools`），再以 `IntegrationMessage` 数组形式送入 SDK。资料来源：[integrations/openclaw/src/types.ts:33-36]()

## 记忆召回工具 (Tool-call) 与 MCP

所有集成共用 `memori_recall` JSON-Schema，包含七个入参：`query`、`dateStart`、`dateEnd`、`projectId`、`sessionId`、`signal`、`source`。`signal` 取自固定 8 项 `SIGNALS`（`commit / discovery / failure / inference / pattern / result / update / verification`），`source` 取自 9 项 `SOURCES`（`constraint / decision / execution / fact / insight / instruction / status / strategy / task`）。资料来源：[integrations/hermes/src/memori_hermes/tools.py:1-66]()

实现层有两条硬约束：

1. `sessionId` 必须与 `projectId` 同时出现，否则工具返回 `{ error: "sessionId cannot be provided without projectId" }` 字符串而非抛异常。资料来源：[integrations/openclaw/src/tools/memori-recall.ts:40-55]()
2. `source` 与 `signal` 必须同时提供或同时省略，且仅接受固定映射 `VALID_PAIRS`（如 `decision → commit`、`fact → verification`、`execution → inference` 等），违规同样以 `error` JSON 返回。资料来源：[integrations/openclaw/src/tools/memori-recall.ts:55-80]()

Hermes 端提供 `memori_recall_summary`（用于每日简报、状态概览）和 `memori_compaction`（上下文压缩后恢复任务态）等补充工具，主系统提示明确指示 Agent "先 recall 再说不记得"。资料来源：[integrations/hermes/src/memori_hermes/__init__.py:25-40]()

MCP 客户端无需安装 SDK：通过 `MEMORI_API_KEY` 环境变量鉴权，并以 HTTP 头 `X-Memori-Process-Id: <process_id>`（如 `claude-code`）携带进程归属；Cursor / Codex / Warp 等客户端的详细步骤见 `docs/memori-cloud/mcp/client-setup.mdx`。资料来源：[README.md:40-55]()

## 常见失败模式

- **未调用 `attribution`**：Rust 核心拒绝写入，表现为 "no memories created"；两类 SDK 的入口都是 `.attribution(entity_id, process_id)`。资料来源：[README.md:60-65]()
- **`source` / `signal` 配对错误**：工具返回 JSON `error` 字符串，Agent 必须将其作为可用信号处理而非抛错。资料来源：[integrations/openclaw/src/tools/memori-recall.ts:55-80]()
- **本地 OpenAI 兼容端点**：当前 `OpenAIIntegration` 默认指向官方端点，Ollama / vLLM 等本地推理需求需等待 Issue #250、#40 的官方支持或自行在 `base_url` 上适配。

## See Also

- 核心流水线：[core/src/augmentation/mod.rs](https://github.com/MemoriLabs/Memori/blob/main/core/src/augmentation/mod.rs)
- 公共 API 类型：[memori-ts/src/types/api.ts](https://github.com/MemoriLabs/Memori/blob/main/memori-ts/src/types/api.ts)
- Hermes 工具集：[integrations/hermes/src/memori_hermes/tools.py](https://github.com/MemoriLabs/Memori/blob/main/integrations/hermes/src/memori_hermes/tools.py)
- 社区需求：Issue **#250**（Ollama/vLLM 支持）、Issue **#40**（本地端点文档）

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：MemoriLabs/Memori

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。

## 1. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/MemoriLabs/Memori | README/documentation is current enough for a first validation pass.

## 2. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/MemoriLabs/Memori | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/MemoriLabs/Memori | no_demo; severity=medium

## 4. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/MemoriLabs/Memori | no_demo; severity=medium

## 5. 安全/权限坑 · 来源证据：Self-hosted (BYODB) usage: `capture_agent_turn()` POSTs to the cloud API, and `Memori(conn=...)` never provisions the s…

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Self-hosted (BYODB) usage: `capture_agent_turn()` POSTs to the cloud API, and `Memori(conn=...)` never provisions the schema — both undocumented
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/MemoriLabs/Memori/issues/590 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 6. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/MemoriLabs/Memori | issue_or_pr_quality=unknown

## 7. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/MemoriLabs/Memori | release_recency=unknown

<!-- canonical_name: MemoriLabs/Memori; human_manual_source: deepwiki_human_wiki -->