# https://github.com/moorcheh-ai/memanto 项目说明书

生成时间：2026-07-02 20:37:30 UTC

## 目录

- [项目概览与系统架构](#page-overview)
- [记忆操作、记忆类型与 CLI 命令](#page-memory-operations)
- [集成生态与 SDK](#page-integrations)
- [部署、配置与安全加固](#page-deployment)

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

## 项目概览与系统架构

### 相关页面

相关主题：[记忆操作、记忆类型与 CLI 命令](#page-memory-operations), [集成生态与 SDK](#page-integrations), [部署、配置与安全加固](#page-deployment)

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

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

- [README.md](https://github.com/moorcheh-ai/memanto/blob/main/README.md)
- [memanto/app/constants.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/constants.py)
- [memanto/app/services/memory_export_service.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/services/memory_export_service.py)
- [memanto/app/services/daily_analysis_service.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/services/daily_analysis_service.py)
- [memanto/app/services/summary_visualization_service.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/services/summary_visualization_service.py)
- [memanto/cli/client/sdk_client.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/cli/client/sdk_client.py)
- [memanto/cli/client/direct_client.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/cli/client/direct_client.py)
- [memanto/cli/commands/migrate.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/cli/commands/migrate.py)
- [memanto/app/legacy/memory.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/legacy/memory.py)
- [sdks/typescript/package.json](https://github.com/moorcheh-ai/memanto/blob/main/sdks/typescript/package.json)
- [integrations/crewai/README.md](https://github.com/moorcheh-ai/memanto/blob/main/integrations/crewai/README.md)
- [integrations/hermes-agents/hermes_memanto/PLUGIN_README.md](https://github.com/moorcheh-ai/memanto/blob/main/integrations/hermes-agents/hermes_memanto/PLUGIN_README.md)
- [examples/langgraph-memanto/README.md](https://github.com/moorcheh-ai/memanto/blob/main/examples/langgraph-memanto/README.md)
- [examples/langgraph-memanto/memanto_base_store/README.md](https://github.com/moorcheh-ai/memanto/blob/main/examples/langgraph-memanto/memanto_base_store/README.md)
</details>

# 项目概览与系统架构

## 项目定位与核心能力

Memanto 是一个面向长时程（long-horizon）智能体的**类型化语义记忆层（typed semantic memory）**，底层依托 Moorcheh 提供信息论检索能力，并提供 CLI、Python/TypeScript SDK、FastAPI 服务以及面向主流智能体框架的集成层。资料来源：[README.md:1-50]()。

其核心能力可以归纳为三点：

1. **13 类语义记忆类型**：涵盖 `fact`、`preference`、`goal`、`decision`、`artifact`、`learning`、`event`、`instruction`、`relationship`、`context`、`observation`、`commitment`、`error`，写入端会携带 `confidence`、`tags`、`source` 等元数据。资料来源：[memanto/app/constants.py:1-15]()`。
2. **Agent（命名空间）抽象**：通过 `support`、`project`、`tool` 三种 `pattern` 划定 memory 作用域，避免跨业务串扰。资料来源：[memanto/cli/client/sdk_client.py:30-75]()`。
3. **多端 SDK + CLI + 服务**：同时提供 Python 直连客户端、TypeScript SDK（`@moorcheh-ai/memanto`，最低支持 Node 20）以及 FastAPI 后端。资料来源：[sdks/typescript/package.json:1-40]()`。

## 系统架构总览

```mermaid
flowchart LR
    U[用户/智能体] -->|CLI/SDK/HTTP| F[FastAPI 服务层<br/>memanto/app/main.py]
    F -->|依赖注入 MoorchehClient| S[领域服务<br/>write/read/recall]
    S -->|v2 memory 路由响应| M[Moorcheh 后端<br/>信息论检索]
    TS[TypeScript SDK<br/>@moorcheh-ai/memanto] -->|OpenAPI 生成类型| F
    I1[CrewAI 工具包装] --> S
    I2[LangGraph MemantoStore] --> S
    I3[Hermes Agents 插件] --> S
    S --> EXP[memory.md 导出/每日摘要]
    S --> MIG[迁移工具<br/>Letta/Mem0/Supermemory]
```

整体自上而下分四层：**接入层**（CLI、SDK、HTTP、各框架集成）→ **服务层**（`memanto.app.services`，含 `DailyAnalysisService`、`MemoryExportService`、`SummaryVisualizationService`）→ **客户端层**（`sdk_client` / `direct_client`，前者走 HTTP、后者直连 Moorcheh）→ **后端层**（Moorcheh 提供存储与检索）。资料来源：[memanto/cli/client/direct_client.py:1-50]()、[memanto/cli/client/sdk_client.py:1-75]()、[memanto/app/services/memory_export_service.py:1-60]()。

## 关键模块划分

### 13 类记忆与导出格式

`memory_export_service.py` 内置了一份 `MEMORY_TYPE_ORDER` 排序与 `MEMORY_TYPE_META` 描述表，按类型顺序渲染 Markdown 章节，标题包含 `## {Label}`，没有数据时显示 `*No memories of this type.*`。资料来源：[memanto/app/services/memory_export_service.py:20-90]()。

### Agent 模式与命名空间

SDK 校验 `pattern ∈ {support, project, tool}` 后构造 `AgentCreate(agent_id, pattern, description)`，所有记忆按 `memanto_agent_{agent_id}` 命名空间隔离。资料来源：[memanto/cli/client/sdk_client.py:30-110]()。

### 每日摘要与可视化

`DailyAnalysisService` 会收集会话期内的 `*_summary.md`，调用 `client.answer.generate` 走 RAG 摘要，再由 `SummaryVisualizationService` 追加 ASCII 时间线、类型分布与置信度概览。资料来源：[memanto/app/services/daily_analysis_service.py:1-90]()、[memanto/app/services/summary_visualization_service.py:1-80]()。

### 迁移 CLI

`memanto migrate` 子命令支持从 Letta、Mem0、Supermemory 三家导出物导入，通过 `_PROVIDER_BUNDLES` 字典统一调度，每个 provider 提供 `export` → LLM 指标 → 报告三段流水线。资料来源：[memanto/cli/commands/migrate.py:1-60]()`。

## SDK、集成与生态

- **TypeScript SDK**：通过 `tsup` 打包、`vitest` 测试，提供 lifecycle hooks、OpenAPI 生成的类型，强依赖 Node ≥ 20。资料来源：[sdks/typescript/package.json:5-40]()。
- **CrewAI**：在 `memanto_tools.py` 中以 Tool 包装 `SdkClient`，并在 `Crew(memory=False)` 中关闭原生 LanceDB 记忆，避免双写。资料来源：[integrations/crewai/README.md:1-40]()。
- **LangGraph**：`MemantoStore` 实现 `BaseStore`，可一行替换 `InMemoryStore`，示例提供 `basic_integration`、`cross_session_recall`、`research_pipeline`、`custom_memory_saver` 四种范式。资料来源：[examples/langgraph-memanto/README.md:1-20]()、[examples/langgraph-memanto/memanto_base_store/README.md:1-40]()。
- **Hermes Agents**：以插件形式暴露 `memanto_remember`、`memanto_recall`、`memanto_answer` 三个工具，支持 `{identity}` 模板实现 Profile 隔离。资料来源：[integrations/hermes-agents/hermes_memanto/PLUGIN_README.md:1-40]()。
- **v0.2.4 版本重点**：新增 `memanto edit` 命令、TypeScript SDK、v2 memory 路由响应模型，并修复跨 Agent 鉴权、上传路径穿越、UI 配置密钥泄露等安全问题。资料来源：[README.md:10-50]()（社区上下文）。

## 常见约束与失败模式

| 关注点 | 当前实现行为 | 资料来源 |
| --- | --- | --- |
| 写入上限 | `batch/write` 单请求最多 100 条，且必须同租户 | [memanto/app/legacy/memory.py:30-90]() |
| 写入白名单 | 仅 `title/content/type/confidence/tags/source` 可更新 | [memanto/app/constants.py:30-55]() |
| 写入策略 | 系统提示在 `cron/flush/subagent` 上下文跳过 | [integrations/hermes-agents/hermes_memanto/PLUGIN_README.md:30-50]() |
| 类型映射 | Letta/Mem0/Supermemory 各自需专用 exporter | [memanto/cli/commands/migrate.py:5-60]() |

## See Also

- [README.md](https://github.com/moorcheh-ai/memanto/blob/main/README.md)
- [docs.memanto.ai](https://docs.memanto.ai)
- [LangGraph 示例总览](https://github.com/moorcheh-ai/memanto/blob/main/examples/langgraph-memanto/README.md)
- [CrewAI 集成说明](https://github.com/moorcheh-ai/memanto/blob/main/integrations/crewai/README.md)

---

<a id='page-memory-operations'></a>

## 记忆操作、记忆类型与 CLI 命令

### 相关页面

相关主题：[项目概览与系统架构](#page-overview), [部署、配置与安全加固](#page-deployment)

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

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

- [memanto/app/constants.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/constants.py)
- [memanto/cli/client/sdk_client.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/cli/client/sdk_client.py)
- [memanto/cli/client/direct_client.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/cli/client/direct_client.py)
- [memanto/app/services/memory_export_service.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/services/memory_export_service.py)
- [memanto/app/services/daily_analysis_service.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/services/daily_analysis_service.py)
- [memanto/app/services/summary_visualization_service.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/services/summary_visualization_service.py)
- [integrations/crewai/README.md](https://github.com/moorcheh-ai/memanto/blob/main/integrations/crewai/README.md)
- [integrations/hermes-agents/hermes_memanto/PLUGIN_README.md](https://github.com/moorcheh-ai/memanto/blob/main/integrations/hermes-agents/hermes_memanto/PLUGIN_README.md)
- [examples/langgraph-memanto/memanto_base_store/README.md](https://github.com/moorcheh-ai/memanto/blob/main/examples/langgraph-memanto/memanto_base_store/README.md)
- [sdks/typescript/package.json](https://github.com/moorcheh-ai/memanto/blob/main/sdks/typescript/package.json)
- [README.md](https://github.com/moorcheh-ai/memanto/blob/main/README.md)

</details>

# 记忆操作、记忆类型与 CLI 命令

Memanto 是一套面向长时程 AI Agent 的"类型化语义记忆"中间层，所有记忆数据通过统一的 13 类记忆类型建模,并通过 Python SDK、TypeScript SDK 与 CLI 三套入口暴露给上层 Agent。本页聚焦于记忆的分类体系、底层服务提供的核心操作（写入、回忆、导出、日报），以及 CLI 与 SDK 对这些操作的封装方式。

## 1. 记忆类型体系

Memanto 使用一个受约束的字面量联合类型来描述可写入的记忆种类。该类型在 [`memanto/app/constants.py`](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/constants.py) 中以 `Literal` 形式声明,并附带运行期校验集合 `VALID_MEMORY_TYPES`:

```python
MemoryType = Literal[
    "fact", "preference", "goal", "decision", "artifact",
    "learning", "event", "instruction", "relationship",
    "context", "observation", "commitment", "error",
]
```

这套类型同时被导出服务 [memory_export_service.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/services/memory_export_service.py) 用来生成"按类型排序"的 Markdown 报告。`MEMORY_TYPE_ORDER` 与 `MEMORY_TYPE_META` 把 13 类记忆归并为一份规范的渲染顺序与人类可读标签,例如 `instruction` → "Instructions / Standing directives and behavioral rules"、`error` → "Errors / Failure records, bugs, and lessons learned"。下游所有 SDK、CrewAI Tools、Hermes 插件、LangGraph Store 都遵守同一份词汇表,从而保证跨 Agent 的检索语义一致(参见 [PLUGIN_README.md](https://github.com/moorcheh-ai/memanto/blob/main/integrations/hermes-agents/hermes_memanto/PLUGIN_README.md) 中"Memos: fact, preference, goal, ..."的列表)。

| 记忆类型 | 中文含义 | 典型用途 |
|---|---|---|
| `instruction` | 指令 | 长期行为规则、角色约束 |
| `fact` / `observation` | 事实 / 观察 | 用户画像、环境信息 |
| `decision` / `commitment` | 决策 / 承诺 | 已确定的选择与待办 |
| `goal` / `preference` | 目标 / 偏好 | 长期意图与个性化 |
| `learning` / `error` | 学习 / 错误 | 经验沉淀与失败记录 |
| `relationship` / `context` | 关系 / 上下文 | 团队与对话状态 |
| `artifact` / `event` | 制品 / 事件 | 文件引用与时间序列 |

> 资料来源：[memanto/app/constants.py:1-20]()、[memanto/app/services/memory_export_service.py]()

## 2. 核心记忆操作

记忆操作分为写入（`remember`）、回忆（`recall`）、回答（`answer`）、冲突解析（`resolve`）和导出（`memory_md`）。这些能力在 Python `SdkClient` 与 `DirectClient` 中以同名方法暴露(参见 [sdk_client.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/cli/client/sdk_client.py) 与 [direct_client.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/cli/client/direct_client.py))。

- **写入**：调用 `remember(agent_id, type, title, content, confidence, tags, ...)` 把单条记忆落到对应 namespace;SDK 内部使用 `AgentCreate` 模型校验 `agent_id` 与 `pattern ∈ {"support", "project", "tool"}`。
- **回忆**：`recall(agent_id, query="*", limit, type=[...])` 基于信息论检索返回 top-k 结果;`type` 参数可传入 13 类中的任意子集做硬过滤。
- **回答**：`answer.generate(namespace, query, ai_model, top_k=50)` 通过 moorcheh 客户端生成基于记忆的 RAG 答案,日报服务正是基于此方法工作。
- **导出**：`memory_md(agent_id, output_path, limit_per_type=25)` 遍历所有 13 类,产出结构化 Markdown 文件,默认输出到 `~/.memanto/exports/{agent_id}_memory.md`(参见 [direct_client.py:memory_md](https://github.com/moorcheh-ai/memanto/blob/main/memanto/cli/client/direct_client.py))。

下面用 Mermaid 描述一次完整"写入 → 回忆 → 导出"的内部数据流:

```mermaid
flowchart LR
    A[Agent / CLI] -->|remember| B(AgentService)
    B --> C[Moorcheh Namespace]
    A -->|recall / answer| C
    C --> D[MemoryExportService]
    D --> E[memory.md by type]
    A -->|memory_md| E
```

> 资料来源：[memanto/cli/client/sdk_client.py]()、[memanto/cli/client/direct_client.py]()、[memanto/app/services/memory_export_service.py]()

## 3. CLI 与自动化命令

CLI 在 `memanto` 命令下提供多个子命令分组:

- **Agent 管理**：`memanto agent create/list/get` 用于注册或查询 Agent;`create` 强制校验 `pattern` 字段必须为 `support/project/tool` 之一。
- **会话管理**：`memanto session` 子命令负责启动、激活、续期与退出 Agent 会话,SDK 在写入前会调用 `_get_validated_session_for_agent` 确保会话未过期。
- **记忆管理**：`memanto memory remember/recall/list/edit`(v0.2.4 新增 `edit` 支持原地更新)、`memanto conflicts resolve` 用于把冲突记忆标记为 `superseded`。
- **导出与日报**：`memanto export memory-md` 触发 `MemoryExportService.write_memory_md`;`memanto daily-analysis` 调用 `DailyAnalysisService.generate_summary` 在指定日期聚合会话文件,并由 LLM 生成自然语言摘要。
- **编辑器接入**：`memanto connect cursor --global` 在 Cursor 中生成 `.cursor/rules/memanto.mdc` 与 `.cursor/skills/memanto/SKILL.md`,使 IDE Agent 直接复用 CLI 命名空间(参见 [integrations/crewai/README.md](https://github.com/moorcheh-ai/memanto/blob/main/integrations/crewai/README.md))。

`DailyAnalysisService.generate_summary` 会先用 glob `{agent_id}_{date}_*_summary.md` 找到当日所有会话摘要,把内容拼接后送给 `client.answer.generate` 生成 Markdown 报告,并自动追加 `SummaryVisualizationService` 提供的 ASCII 时间线、类型分布与置信度可视化块(参见 [daily_analysis_service.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/services/daily_analysis_service.py) 与 [summary_visualization_service.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/services/summary_visualization_service.py))。

## 4. 集成 SDK 与已知边界

官方在 v0.2.4 同时发布了 TypeScript SDK `@moorcheh-ai/memanto`,提供 lifecycle hooks 与 OpenAPI 生成的类型,运行时要求 `node>=20`(参见 [sdks/typescript/package.json](https://github.com/moorcheh-ai/memanto/blob/main/sdks/typescript/package.json))。在第三方框架层:

- **CrewAI**：通过工具包装 `SdkClient`,在 Crew 上显式设置 `memory=False` 以避免与内置 LanceDB 记忆冲突;命名空间 `memanto_agent_{agent_id}` 提供隔离边界。
- **Hermes Agents**：插件按 `{identity}` 模板拆分 agent,在 `cron/flush/subagent` 上下文跳过写入,防止污染用户记忆。
- **LangGraph**：`MemantoStore(BaseStore)` 实现 LangGraph 官方存储接口;`PutOp(value=None)` 删除会抛 `NotImplementedError`,官方明确建议改走 `memanto conflicts resolve` 流程(参见 [memanto_base_store/README.md](https://github.com/moorcheh-ai/memanto/blob/main/examples/langgraph-memanto/memanto_base_store/README.md))。

常见失败模式包括:把 LLM 自动抽取的内容直接当作唯一来源(应使用 Memanto 工具写入以保留 13 类元数据)、跨 Agent 直接共享 `api_key`(v0.2.4 已修复跨 Agent 鉴权)、上传路径穿越(同版本修复)以及 UI 配置端点泄露密钥(同版本修复)。

## See Also

- [README.md](https://github.com/moorcheh-ai/memanto/blob/main/README.md)
- 集成示例:[CrewAI](./integrations-crewai.md)、[Hermes Agents](./integrations-hermes.md)、[LangGraph BaseStore](./integrations-langgraph.md)
- TypeScript SDK 参考:[sdks/typescript](../sdks-typescript/index.md)

---

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

## 集成生态与 SDK

### 相关页面

相关主题：[项目概览与系统架构](#page-overview), [记忆操作、记忆类型与 CLI 命令](#page-memory-operations)

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

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

- [sdks/typescript/package.json](https://github.com/moorcheh-ai/memanto/blob/main/sdks/typescript/package.json)
- [memanto/cli/client/sdk_client.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/cli/client/sdk_client.py)
- [memanto/cli/client/direct_client.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/cli/client/direct_client.py)
- [examples/langgraph-memanto/README.md](https://github.com/moorcheh-ai/memanto/blob/main/examples/langgraph-memanto/README.md)
- [examples/langgraph-memanto/memanto_base_store/README.md](https://github.com/moorcheh-ai/memanto/blob/main/examples/langgraph-memanto/memanto_base_store/README.md)
- [integrations/crewai/README.md](https://github.com/moorcheh-ai/memanto/blob/main/integrations/crewai/README.md)
- [integrations/hermes-agents/hermes_memanto/PLUGIN_README.md](https://github.com/moorcheh-ai/memanto/blob/main/integrations/hermes-agents/hermes_memanto/PLUGIN_README.md)
- [memanto/app/constants.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/constants.py)
- [memanto/cli/commands/migrate.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/cli/commands/migrate.py)
- [memanto/app/services/daily_analysis_service.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/services/daily_analysis_service.py)
- [memanto/app/services/memory_export_service.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/services/memory_export_service.py)
</details>

# 集成生态与 SDK

Memanto 的设计目标是成为 AI Agent 的"持久化外脑"。围绕这一目标,项目提供了多语言 SDK、主流 Agent 框架集成以及配套的数据迁移与分析工具,形成完整的生态体系。本文聚焦 v0.2.4 发布版涉及的 SDK 与集成层。

## SDK 总览

### TypeScript SDK

v0.2.4 正式发布了官方 TypeScript 包 `@moorcheh-ai/memanto`。其 `package.json` 表明 SDK 面向 Node `>=20`,构建工具链使用 `tsup` 与 `TypeScript ^5.4`,测试框架为 `vitest ^4.1.9`;仓库元数据以 `"directory": "sdks/typescript"` 明确指向 monorepo 内的子目录,与 CLI 端的 Python 实现共享 OpenAPI 生成的类型。  
资料来源:[sdks/typescript/package.json]()

### Python CLI Client

Python 侧没有单独的 pip 包,而是通过 `memanto/cli/client/` 下的 `SdkClient` 与 `DirectClient` 提供两类入口。`SdkClient` 走 REST API,`DirectClient` 则直接调用本地服务层的 Agent / Memory / Export 模块。两者都实现了 `create_agent`、`list_agents`、`get_agent`、`export_memory_md` 等统一方法,以便在不同部署模式下保持一致的编程语义。  
资料来源:[memanto/cli/client/sdk_client.py]() [memanto/cli/client/direct_client.py]()

## 框架集成

```mermaid
flowchart LR
    A[应用代码] --> B{框架层}
    B -->|LangGraph| C[MemantoStore<br/>BaseStore]
    B -->|CrewAI| D[memanto_tools<br/>Tool 包装]
    B -->|Hermes| E[hermes-memanto<br/>plugin]
    C --> F[Python SdkClient]
    D --> F
    E --> G[CLI / HTTP]
    F --> H[Memanto 服务]
    G --> H
```

### LangGraph

`examples/langgraph-memanto/` 下提供四个示例子目录:基础接入、跨会话记忆、研究流水线与自定义 `CheckpointSaver` 集成。其中 `memanto_base_store` 把 `MemantoStore` 实现成 `langgraph.store.BaseStore`,开发者仅需一行替换即可将 `InMemoryStore` 升级为持久化的语义记忆后端。该适配层把 LangGraph 的 `PutOp.value` 字段映射到 Memanto 的 `memory_type` / `title` / `content` / `confidence` / `tags`,把 `SearchOp` 转换为 recall 查询。需要注意的是:`PutOp(value=None)` 的删除语义会抛出 `NotImplementedError`,应改走 `memanto conflicts resolve`;`ttl` 与 `offset` 分页在 BaseStore 适配中被忽略。  
资料来源:[examples/langgraph-memanto/README.md]() [examples/langgraph-memanto/memanto_base_store/README.md]()

### CrewAI

`integrations/crewai/` 采用 Tool 包装模式(而非 `StorageBackend`),目的是让 LLM 在写入时自主选择 13 种记忆类型之一,并附带 `confidence` 与 `tags`。示例中所有 Crew 显式设置 `memory=False`,避免与 Memanto 工具重复存储;Research Agent 与 Writer Agent 共享 `crewai-research-team` 这一个 agent_id,通过 Memanto 的 scope 机制实现隔离。  
资料来源:[integrations/crewai/README.md]()

### Hermes Agents

`hermes_memanto` 以插件方式暴露 `memanto_remember` / `memanto_recall` / `memanto_answer` 三个工具,并支持 `auto_recall`、`auto_capture`、`mirror_memory_writes` 等行为。`agent_id` 中使用 `{identity}` 占位符可按 Hermes profile 区分命名空间(如 `hermes-coder`),缺省回退到 `hermes-default`。后台会在启动时预热会话以摊薄首次召回延迟;`cron`/`flush`/`subagent` 上下文会跳过写入,防止污染用户记忆。  
资料来源:[integrations/hermes-agents/hermes_memanto/PLUGIN_README.md]()

## 公共契约:记忆类型体系

所有 SDK 与集成共享同一份类型清单。`memanto/app/constants.py` 通过 `MemoryType` 字面量集合定义了 13 种语义记忆:`fact`、`preference`、`goal`、`decision`、`artifact`、`learning`、`event`、`instruction`、`relationship`、`context`、`observation`、`commitment`、`error`,同名的 `VALID_MEMORY_TYPES` 用于运行时校验。`VALID_PATTERNS = {"support", "project", "tool"}` 决定 `create_agent` 时可选取的命名空间模板。  
资料来源:[memanto/app/constants.py]()

## 配套生态工具

`memanto/cli/commands/migrate.py` 把 Letta、mem0、Supermemory 三家外部系统的导出、指标计算、报告生成统一封装成 `_PROVIDER_BUNDLES` 字典,每个子命令只需挑选对应 bundle,降低了迁移路径的样板代码。`DailyAnalysisService.generate_summary` 通过 `moorcheh_client.answer.generate` 把当日会话聚合成自然语言日报,并调用 `SummaryVisualizationService` 追加 ASCII 时间线、类型分布与置信度可视化。`MemoryExportService` 提供 `export_memory_md`,按 `MEMORY_TYPE_ORDER` 中声明的顺序输出结构化 Markdown,便于人工审阅或喂给其他工具。  
资料来源:[memanto/cli/commands/migrate.py]() [memanto/app/services/daily_analysis_service.py]() [memanto/app/services/memory_export_service.py]()

## 常见使用模式

1. **SDK 直连**:Node 端引入 `@moorcheh-ai/memanto`,使用生命周期钩子在 Agent 启动时创建/激活命名空间,结束时优雅关闭;Python 端则通过 `SdkClient` 走 HTTP,适合 sidecar 部署。
2. **框架嵌入**:在 LangGraph 中替换 `BaseStore`,在 CrewAI 中追加 tool,在 Hermes 中启用 plugin,均无需重写业务节点。
3. **数据迁移与审计**:从其他记忆系统迁入时使用 `memanto migrate <provider>`;日常审计则用 `memanto export memory-md` + `DailyAnalysisService` 生成日报。

## 故障排查要点

- `MOORCHEH_API_KEY` 未配置会导致所有集成在首次调用时抛错,务必复制 `.env.example` 为 `.env`。
- LangGraph `BaseStore` 的 `delete` 走的是 Memanto 的冲突解决流程,需用 `memanto conflicts resolve`。
- TypeScript SDK 要求 Node `>=20`,旧版本会出现 ESM 解析错误。

## See Also

- Memanto CLI 命令参考
- Moorcheh 后端向量存储
- 记忆类型与 provenance 模型
- 安全加固:跨 Agent 鉴权与路径遍历修复(v0.2.4)

---

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

## 部署、配置与安全加固

### 相关页面

相关主题：[项目概览与系统架构](#page-overview), [记忆操作、记忆类型与 CLI 命令](#page-memory-operations)

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

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

- [memanto/cli/commands/config_cmd.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/cli/commands/config_cmd.py)
- [memanto/cli/config/manager.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/cli/config/manager.py)
- [memanto/app/config.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/config.py)
- [memanto/app/main.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/main.py)
- [memanto/app/clients/backend.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/clients/backend.py)
- [memanto/app/clients/onprem.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/clients/onprem.py)
- [memanto/cli/client/sdk_client.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/cli/client/sdk_client.py)
- [memanto/cli/client/direct_client.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/cli/client/direct_client.py)
- [memanto/app/constants.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/constants.py)
- [sdks/typescript/package.json](https://github.com/moorcheh-ai/memanto/blob/main/sdks/typescript/package.json)
- [README.md](https://github.com/moorcheh-ai/memanto/blob/main/README.md)
</details>

# 部署、配置与安全加固

Memanto 提供多形态的部署路径（托管后端 + 本地 SDK）与一致的安全模型。本页聚焦三大主题：CLI/配置文件驱动的运行期配置、Python 与 TypeScript 双端的发布形态，以及 v0.2.4 版本中针对授权与凭据泄露的加固措施。

## 配置管理

### CLI 配置入口

`memanto` 的运行期配置由 `memanto/cli/commands/config_cmd.py` 中的子命令族统一管理，配合 `memanto/cli/config/manager.py` 中的 `ConfigManager` 进行读写。常见的配置维度包括：API Key、默认智能体模式（`support` / `project` / `tool`）、命名空间前缀等。

`memanto/app/constants.py` 中通过枚举将可选值集中收敛，确保 CLI 接收的字符串参数在进入服务层前就被校验：

```python
资料来源：[memanto/app/constants.py:VALID_PATTERNS]()
VALID_PATTERNS = {"support", "project", "tool"}
VALID_MEMORY_TYPES = { "fact", "preference", "goal", "decision", ... }
```

### 服务端配置加载

服务端通过 `memanto/app/config.py` 读取环境变量并构造 `Settings` 对象，`memanto/app/main.py` 在应用启动时挂载到 FastAPI 生命周期中。CLI 子命令（如 `migrate`、`edit`、`conflicts`）均通过 `_shared.get_client` 复用同一份配置上下文，避免在多入口下出现配置漂移（资料来源：[memanto/cli/commands/_shared.py:config_manager]()）。

## 部署模式

### 双端 SDK 发布

Python 端通过 `SdkClient`（位于 `memanto/cli/client/sdk_client.py`）暴露同构 API，而 TypeScript 端则以 `@moorcheh-ai/memanto` 包发布，其构建工具链与运行时要求在 `sdks/typescript/package.json` 中固化：

| 项目 | 值 | 说明 |
|------|----|------|
| 运行时 | `node >=20` | 最低 Node 版本要求 |
| 构建工具 | `tsup ^8.0.0` | 单命令打包 ESM/CJS 双产物 |
| 测试框架 | `vitest ^4.1.9` | 配套单元测试运行器 |
| 类型来源 | OpenAPI 生成 | 保持与 REST 路由一致 |

### 后端与本地形态

托管后端通过 `memanto/app/clients/backend.py` 调用 Moorcheh API；本地/离线场景使用 `memanto/app/clients/onprem.py`。两种客户端在 `SdkClient` 内部被同一组工厂方法（`_get_agent_service`、`_get_memory_service` 等）包装，对上层业务保持接口一致。

```mermaid
flowchart LR
    A[CLI / SDK] --> B[ConfigManager]
    B --> C[Settings]
    C --> D[backend.py]
    C --> E[onprem.py]
    D --> F[Moorcheh Cloud]
    E --> G[Local Vector Store]
```

## 安全加固（v0.2.4）

v0.2.4 集中修复了三类高风险问题，所有变更均围绕"凭据与边界"展开：

- **跨智能体授权**：原先对智能体 ID 的校验存在越权读取风险；现已在服务端校验调用方 API Key 是否具备目标命名空间（`memanto_agent_{agent_id}`）的访问权（资料来源：[memanto/app/main.py:auth_dependency]()）。
- **上传路径遍历**：附件上传时统一通过 `Path.resolve()` + 白名单目录前缀校验，杜绝 `../` 逃逸到 `data/` 之外（资料来源：[memanto/app/clients/backend.py:upload_file]()）。
- **UI 配置端点密钥泄露**：`/config` 端点不再回显明文 API Key，仅返回脱敏后的指纹与最后修改时间（资料来源：[memanto/app/main.py:config_router]()）。

## 故障排查与最佳实践

- **API Key 未设置**：在 CLI 中执行 `memanto config set api-key`，或在 `.env` 中导出 `MOORCHEH_API_KEY`（参考 `integrations/crewai/README.md` 中的 `.env.example`）。
- **智能体模式错误**：仅接受 `support`、`project`、`tool`，其余值会在 CLI 入口抛出 `ValueError`（资料来源：[memanto/cli/client/direct_client.py:create_agent]()）。
- **TypeScript SDK 安装**：`npm install @moorcheh-ai/memanto`，构建前确保 Node ≥ 20（资料来源：[sdks/typescript/package.json:engines]()）。
- **本地部署**：将 `Settings.backend` 切到 `onprem`，无需联网即可完成 recall/remember 全流程。

## See Also

- CLI 命令参考（`memanto edit`、`memanto conflicts resolve`）
- TypeScript SDK 生命周期钩子
- v2 Memory Route 响应模型变更说明

---

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

---

## Doramagic 踩坑日志

项目：moorcheh-ai/memanto

摘要：发现 10 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：[BOUNTY $100] 🐜 The Great Agentic Memory Showdown: Memanto Benchmarking & Evaluation Challenge。

## 1. 安全/权限坑 · 来源证据：[BOUNTY $100] 🐜 The Great Agentic Memory Showdown: Memanto Benchmarking & Evaluation Challenge

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[BOUNTY $100] 🐜 The Great Agentic Memory Showdown: Memanto Benchmarking & Evaluation Challenge
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/moorcheh-ai/memanto/issues/639 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 2. 安全/权限坑 · 来源证据：[BOUNTY $100] 🐜The Memanto Bug & Exploit Challenge

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[BOUNTY $100] 🐜The Memanto Bug & Exploit Challenge
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/moorcheh-ai/memanto/issues/770 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 3. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://github.com/moorcheh-ai/memanto | host_targets=claude_code, claude, cursor

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

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

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

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

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

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

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

## 8. 安全/权限坑 · 来源证据：`detect-conflicts` (on-prem) fails on any active day because the conflict query exceeds the embedding model's context w…

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：`detect-conflicts` (on-prem) fails on any active day because the conflict query exceeds the embedding model's context window
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/moorcheh-ai/memanto/issues/1329 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

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

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

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

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

<!-- canonical_name: moorcheh-ai/memanto; human_manual_source: deepwiki_human_wiki -->