项目定位与核心能力

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`。

系统架构总览

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（社区上下文）。

常见约束与失败模式

See Also

• README.md
• docs.memanto.ai
• LangGraph 示例总览
• CrewAI 集成说明

1. 记忆类型体系

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

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

这套类型同时被导出服务 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 中"Memos: fact, preference, goal, ..."的列表)。

资料来源：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 与 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)。

下面用 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)。

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

4. 集成 SDK 与已知边界

官方在 v0.2.4 同时发布了 TypeScript SDK @moorcheh-ai/memanto,提供 lifecycle hooks 与 OpenAPI 生成的类型,运行时要求 node>=20(参见 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)。

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

See Also

• README.md
• 集成示例:CrewAI、Hermes Agents、LangGraph BaseStore
• TypeScript SDK 参考:sdks/typescript

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

框架集成

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)

配置管理

CLI 配置入口

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

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

资料来源：[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 中固化：

后端与本地形态

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

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 响应模型变更说明

Pitfall Log / 踩坑日志

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