Memori 项目说明书 - Doramagic.ai

Doramagic 项目包 · 项目说明书

Memori 项目

Memori 是面向 Agent 的原生记忆基础设施，作为与 LLM 无关的中间层，可将智能体的执行过程和对话转化为结构化、可持久化的状态，适用于生产系统。

Memori Overview & System Architecture

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

章节 相关页面

继续阅读本节完整说明和来源证据。

Memori 概述与系统架构

1. 项目定位与设计理念

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

2. 系统总体架构

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

Advanced Augmentation（高级增强）：在每次交互后，Memori 将原始会话数据异步转换为结构化、可复用的记忆单元，捕获代理动作、推理、工具使用、回复、纠正与失败，并生成向量嵌入以支持语义检索。资料来源：integrations/openclaw/README.md:60-100
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

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 集成概览
Hermes 记忆提供方 API
TypeScript SDK 类型参考

来源：https://github.com/MemoriLabs/Memori / 项目说明书

Python & TypeScript SDKs and Rust Core

Memori 项目由三个紧密协作的层级组成：底层的 Rust 核心（engine-orchestrator）、中间的 Python / TypeScript SDK、以及上层面向不同 LLM 框架与 CLI 的集成包（Hermes、OpenClaw、Claude Code 等）。最新发行版本为 3.3.6（参见 PR 561、562、563），其中 fastembed 已被...

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 模块组成

继续阅读本节完整说明和来源证据。

章节 工作运行时配置

继续阅读本节完整说明和来源证据。

章节 检索与扩展流程

继续阅读本节完整说明和来源证据。

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。

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 类型问题，提示用户在升级后注意：

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

BYODB Storage Layer & Local OpenAI-Compatible Endpoints

Memori 是一个面向 LLM 代理的结构化、长期记忆系统，其核心定位是 "LLM、数据存储与框架均无关"——可以接入已有的软件与基础设施体系 README.md。在这一原则下，项目提供两条互补的部署路径：Memori Cloud（零配置托管）与 BYODB（Bring Your Own Database，自带数据库）；同时支持多种 LLM 提供方，包括 OpenAI、A...

章节 相关页面

继续阅读本节完整说明和来源证据。

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

概览与定位

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

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

BYODB 存储架构

BYODB 模式允许开发者将 Memori 直接部署到自有数据库上。根据 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。

嵌入生成由 fastembed 后端提供 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。

读取路径位于 core/src/retrieval/mod.rs，由 pipeline::run_retrieval 执行检索，再经 format_recall_output 序列化为可注入提示的回忆内容 core/src/retrieval/mod.rs。

本地 OpenAI 兼容端点

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

在 Memori 的设计中，LLM 提供方通过拦截器解耦——上层只需把请求/响应轨迹送入记忆管线，不必关心底层是 OpenAI 还是自托管的兼容服务 README.md。Hermes 集成展示了这一模式的落地方式：MemoriAgentClient 通过 from memori import Memori 引入 SDK，并接受 api_key 与可选的 base_url 参数 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。

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

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

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

Advanced Augmentation（高级增强）——异步把原始会话转化为结构化记忆单元，捕获代理的工具调用、决策、结果与失败，并生成嵌入用于语义检索 integrations/openclaw/README.md。
Agent-Controlled Recall（代理控制回忆）——以显式工具形式暴露，例如 Hermes 提供器的 memori_recall 与 memori_recall_summary 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。worker.rs 中的 OutstandingGuard 在任务被丢弃时递减计数并唤醒等待者，确保 LLM 调用不会因记忆管线阻塞而延迟 core/src/runtime/worker.rs。

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 / 项目说明书

LLM Provider Adapters, Framework Integrations & MCP

Memori 官方定位为 "LLM、data store、framework 都无关 (agnostic) 的可插拔记忆层"：通过 Adapter（适配器）接入上游 LLM 客户端，通过 Framework Integration（框架集成）让 Agent 框架主动使用结构化记忆工具，并通过 MCP 客户端设置把任何兼容 MCP 的 IDE / CLI（如 Curso...

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 Hermes Agent（Python）

继续阅读本节完整说明和来源证据。

章节 OpenClaw（TypeScript / Node ≥ 22）

继续阅读本节完整说明和来源证据。

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

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

实现层有两条硬约束：

sessionId 必须与 projectId 同时出现，否则工具返回 { error: "sessionId cannot be provided without projectId" } 字符串而非抛异常。资料来源：integrations/openclaw/src/tools/memori-recall.ts:40-55
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 上适配。

失败模式与踩坑日记

保留 Doramagic 在发现、验证和编译中沉淀的项目专属风险，不把社区讨论只当作装饰信息。

medium 能力判断依赖假设

假设不成立时，用户拿不到承诺的能力。

medium 维护活跃度未知

新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。

medium 存在评分风险

风险会影响是否适合普通用户安装。

medium 来源证据：Self-hosted (BYODB) usage: `capture_agent_turn()` POSTs to the cloud API, and `Memori(conn=...)` never provisions the s…

可能影响授权、密钥配置或安全边界。

Pitfall Log / 踩坑日志

项目：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

来源：Doramagic 发现、验证与编译记录

Memori 项目

Memori Overview & System Architecture

Memori 概述与系统架构

1. 项目定位与设计理念

2. 系统总体架构

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

4. 集成生态与故障容错

另请参阅

Python & TypeScript SDKs and Rust Core

Python 与 TypeScript SDK 以及 Rust Core

总体定位与分层架构

Rust Core：引擎核心

模块组成

工作运行时配置

检索与扩展流程

Python 与 Node 绑定

上层集成：Hermes、OpenClaw、Claude Code

Hermes（Python）

OpenClaw（Node）

Claude Code

社区关注点与版本说明

See Also

BYODB Storage Layer & Local OpenAI-Compatible Endpoints

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

概览与定位

BYODB 存储架构

本地 OpenAI 兼容端点

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

常见问题与故障排查

另请参阅

LLM Provider Adapters, Framework Integrations & MCP

LLM Provider Adapters、Framework Integrations 与 MCP

概述

LLM Provider Adapters

Framework Integrations

Hermes Agent（Python）

OpenClaw（TypeScript / Node ≥ 22）

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

常见失败模式

See Also

失败模式与踩坑日记

Pitfall Log / 踩坑日志

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

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

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

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

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

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