系统定位与核心能力

mnemo 是一个面向 AI 编码代理的本地记忆系统。它把"问题、解决方案、推理过程"这类长寿命知识以带类型的 Memory 形式持久化到本地，并通过 MCP 协议与 CLI 两条入口暴露给宿主代理。从 0.3.0 版本起，记忆不仅可以被检索（search / browse），还能回答问题——recall 工具会基于项目记忆合成一个有据可查的回答，并在没有相关记忆时返回 No relevant memories found.，绝不依赖模型的世界知识 资料来源：src/mnemo/application/use_cases/recall_project.py:1-15。

CLI 的自描述把这种定位浓缩成一句话："mnemo - local memory for AI coding agents. Store and search typed memories locally." 资料来源：src/mnemo/adapters/cli/app.py:1-15。MCP 端的 remember 工具也明确写着 "No LLM runs on write"——写入是纯结构化的，没有模型开销 资料来源：src/mnemo/adapters/mcp/server.py:1-30。

架构分层与依赖注入

系统采用经典的端口—适配器 + 用例（hexagonal）分层，所有用例在容器启动时一次性绑定到具体的实现：

flowchart TB
  subgraph Entry["接入层 (Adapters)"]
    CLI["CLI (Typer)<br/>store / recall / ..."]
    MCP["MCP Server<br/>remember / search / browse"]
  end
  subgraph App["应用层 (Use Cases)"]
    Remember["RememberMemory"]
    Search["SearchMemory"]
    Browse["BrowseMemory"]
    Recall["RecallProject"]
    Proj["Create/Update/List/Delete Project"]
    Del["DeleteMemory"]
  end
  subgraph Domain["领域层"]
    Memory["Memory entity"]
    Scope["Scope / MemoryType"]
  end
  subgraph Infra["基础设施 (llmkit + repos)"]
    Embedder["TextEmbedder (hash | pplx)"]
    Reranker["Reranker (opt)"]
    Generator["Generator (opt)"]
    Repo["MemoryRepository / ProjectRepository"]
  end
  CLI --> App
  MCP --> App
  App --> Domain
  App --> Infra

build_container() 把所有用例串成一个对象图：remember、search、browse、recall、delete 以及项目相关的若干用例统一装配；其中 recall 用例会拿到可选的 reranker 与 generator，由配置决定是否注入 资料来源：src/mnemo/infrastructure/composition.py:1-25。这种"全用例聚合到一个容器对象"的设计，让 CLI 和 MCP 只需调用一次 build_container() 就能拿到完整服务集，避免重复装配。

核心数据模型与 Recall 管道

Memory 是顶层实体，包含 content、type、scope、project、related_files、tags、topic_key、session_id、status、supersedes、hash、created_at、updated_at 等字段，并通过 Memory.create() 工厂方法强制校验——空内容会被拒绝，scope=GLOBAL 时 project 自动归一为 GLOBAL_PROJECT 资料来源：src/mnemo/domain/memory.py:1-30。

recall 是 0.3.0 的核心能力，背后是一条多阶段管道：

1. 检索：用 TextEmbedder 把 query 编码成向量后取回相关记忆；
2. 重排：可选的 Reranker 重新排序前 top_k；
3. 组装：AssembleStage 把记忆按 type.value 分组，形成 RecallSection；
4. 生成：可选的 Generator（如 Gemma 4 E2B-it 官方 QAT GGUF）综合成回答文本。

RecallBundle 始终承载结构化分组，summary 仅在生成阶段运行后才被填充——这意味着即使关闭生成器，bundle 仍然自带结构信息 资料来源：src/mnemo/application/recall/bundle.py:1-20。AssembleStage 是纯函数，不依赖模型，因此可以作为未来 LLM 合成阶段的稳定接缝 资料来源：src/mnemo/application/recall/assemble_stage.py:1-20。

双入口与混合检索语义

CLI 与 MCP 共享同一份容器，但呈现形式不同：CLI 默认把 recall 结果以 JSON 打印，并把模型耗时/内存写到日志（受 MNEMO_LOG_LEVEL 控制）；MCP 则把 recall / search / browse 暴露为工具，给 AI 代理调用 资料来源：src/mnemo/adapters/cli/app.py:25-60 资料来源：src/mnemo/adapters/mcp/server.py:1-50。

检索层有一条被显式保护的不变量：Retrieval 对象要求 text 与 vector 要么同时存在、要么都不存在——单独存在任何一半都会被构造函数拒绝，因为这意味着 store 将只用一半信号排序，几乎总是调用方构造请求时的 bug（例如忘了把 query 编码成向量）。这条规则将错误前移到用例边界，避免在存储层深处崩溃 资料来源：src/mnemo/application/retrieval.py:1-30。

可选模型与依赖边界

模型相关能力被刻意隔离在 llmkit 子包内，仅暴露 Generator、Reranker、Nli 等 Protocol 端口以及 Vector / NliScores 等共享类型 资料来源：src/llmkit/ports/nli.py:1-10 资料来源：src/llmkit/types.py:1-15。ModelConfig 用 OnnxSource / GgufSource 描述模型来源，用 Residency（默认 Transient）描述加载策略，且这些选项由消费者在代码里选定，不通过环境变量读取 资料来源：src/llmkit/config.py:1-15。

默认嵌入器走 hash 路径——确定性、无外部依赖、纯词袋——用于离线/测试骨架；生产路径是 pplx-embed-v1-0.6b 的 int8 ONNX 模型，由 llmkit 的 ONNX 编码器托管 资料来源：src/mnemo/adapters/embedding/hash_embedder.py:1-25 资料来源：src/mnemo/infrastructure/composition.py:10-25。如果用户没装 mnemo[recall] 额外依赖，reranker/generator 适配器会抛出可操作的 RuntimeError，CLI 将其打印为一行错误而非 traceback 资料来源：src/mnemo/adapters/cli/app.py:40-55。

项目管理作为一等公民

除了记忆实体本身，mnemo 还把 Project 提升为一等公民：项目有独立的用例 CreateProjectUseCase、UpdateProjectUseCase、DeleteProjectUseCase、ListProjectsUseCase，以及一个无 query 的 BrowseMemoryUseCase 用例 资料来源：src/mnemo/application/use_cases/interfaces/create_project.py:1-5 资料来源：src/mnemo/application/use_cases/interfaces/update_project.py:1-5 资料来源：src/mnemo/application/use_cases/interfaces/delete_project.py:1-5 资料来源：src/mnemo/application/use_cases/interfaces/list_projects.py:1-5 资料来源：src/mnemo/application/use_cases/interfaces/browse_memory.py:1-15。

UpdateProjectUseCaseImpl 的文档注释特别指出：描述字段是后续项目级语义近似匹配（tier-2）的输入，因此需要与创建解耦、允许独立编辑 资料来源：src/mnemo/application/use_cases/update_project.py:1-15。这种"项目元数据可演化、记忆内容亦可演化（通过 topic_key 复用）"的双轨设计，让长期使用下的知识库可以保持整洁而不重复。

See Also

• Recall 功能详解（recall 管道、bundle 字段、生成器配置）
• CLI 命令参考（store / recall / project 子命令）
• MCP 工具参考（remember / search / browse / recall）
• Memory 与 Project 领域模型

概述与设计目标

recall 是 mnemo 0.3.0 引入的唯一可选 LLM 读路径，它把"按相关性检索"升级为"按问题回答"。在 CLI 中通过 mnemo recall <project> <query> 调用 资料来源：src/mnemo/adapters/cli/app.py;在 MCP 中通过 recall 工具暴露 资料来源：src/mnemo/adapters/mcp/server.py。

它的设计目标有三条：

1. 回答而非罗列：生成器（默认 Gemma 4 E2B-it 官方 QAT GGUF）从一批相关记忆合成简洁、有据可查的答复。
2. 永远基于记忆：当无相关记忆时，模型必须回复固定拒绝语 No relevant memories found.，禁止使用外部知识。
3. 模型可降级：reranker 与 generator 都是可选端口——只有当对应模型被配置时才会进入管线；没有生成器时，recall 回退为按类型分组的结构化结果。

资料来源：src/mnemo/application/use_cases/recall_project.py:1-15、src/mnemo/application/recall/synthesis_prompt.py:1-15。

管线架构与阶段

build_recall_pipeline 根据可用端口动态拼装阶段，遵循"embedder -> reranker -> generator，每项精炼各司其职"的退化哲学。资料来源：src/mnemo/application/recall/builder.py:1-44。

flowchart LR
    A[RecallRequest<br/>project + query + limit] --> B[GatherStage<br/>hybrid retrieve]
    B --> C{Reranker?}
    C -- configured --> D[RerankStage<br/>re-order by query]
    C -- none --> E
    D --> E[AssembleStage<br/>group by type]
    E --> F{Generator?}
    F -- configured --> G[SynthesizeStage<br/>LLM prose]
    F -- none --> H
    G --> H[RecallBundle<br/>sections + summary?]

GatherStage（必备）：调用相同的混合检索（嵌入 + 词法），使用 SearchCriteria(scope="project", project=request.project)，并把检索结果放入 GATHERED 槽位。资料来源：src/mnemo/application/recall/gather_stage.py:1-39。

RerankStage（可选）：当注入 Reranker 时插入，按查询对 GATHERED 重排，top_k=20。资料来源：src/mnemo/application/recall/rerank_stage.py。

AssembleStage（必备）：纯函数，把 GATHERED 按 memory.type.value 分组到 RecallSection，产出 RecallBundle(project, sections)。资料来源：src/mnemo/application/recall/assemble_stage.py:1-26。

SynthesizeStage（可选）：当注入 Generator 时追加；空 bundle 直接 no-op（无内容可总结），否则调用 build_synthesis_prompt 并用 dataclasses.replace 原地填充 summary 字段。资料来源：src/mnemo/application/recall/synthesize_stage.py:1-30。

数据契约：Request、Bundle 与拒绝语

输入 RecallRequest 是 frozen dataclass，__post_init__ 显式拒绝空查询——空查询会静默退化为"无导向转储"，因此被 ValueError 拦截并给出可操作提示。资料来源：src/mnemo/application/recall/request.py:1-26。

输出 RecallBundle 始终携带结构化分组；summary 只有在生成器阶段运行后才会被填充。RecallSection 持有 (type, memories) 元组；RecallBundle.total 聚合所有 section 的记忆数。资料来源：src/mnemo/application/recall/bundle.py:1-31。

合成 prompt 模板把记忆按类型排版（## <type> 分组），先列记忆再重复问题以重新锚定注意力；指令明确要求只用给定记忆、不得使用外部知识，并在不相关时输出 No relevant memories found.。资料来源：src/mnemo/application/recall/synthesis_prompt.py:1-44。

集成点、配置与失败模式

infrastructure/composition.py 中的 build_container 在 recall 字段上装配管线，依赖注入全部来自 Config：

资料来源：src/mnemo/infrastructure/composition.py

常见失败模式：

• 空查询：RecallRequest.__post_init__ 抛 ValueError，CLI 转为 typer.BadParameter。资料来源：src/mnemo/application/recall/request.py:18-25、src/mnemo/adapters/cli/app.py。
• 缺失可选端口：CLI 捕获 RuntimeError 并以 typer.Exit(1) 输出可操作消息（不再打印 traceback）。资料来源：src/mnemo/adapters/cli/app.py。
• MCP 视图轻量化：recall MCP 工具返回 {project, summary, 资料来源：[{id,type}, …]}，刻意省略记忆正文以减轻调用方上下文负担。资料来源：src/mnemo/adapters/mcp/server.py。

See Also

• Memory Domain Model — Memory 实体与不变量
• Search & Retrieval — GatherStage 复用的混合检索路径
• CLI Commands — store/search/browse/recall 等命令参考
• MCP Server — recall 工具与上下文裁剪策略

数据模型、存储与记忆操作

Memory 实体：域核心与写入不变式

Memory 是 mnemo 中唯一被持久化的领域实体——它承载 agent 跨会话需要保留的所有决策、bug、进度与规则片段。所有 Memory 实例都通过 Memory.create() 工厂方法构造，而非直接调用构造函数，从而在写入前强制执行关键不变式检查。

工厂在校验阶段分别处理：not content or not content.strip() 拒绝空内容；Scope(scope) 与 MemoryType(type) 把字符串入参归一化为枚举；当 scope is Scope.GLOBAL 时直接把 project 覆盖为 GLOBAL_PROJECT，从而保证后续"项目内 + 全局"联合查询的语义一致。topic_key 复用路径返回 "superseded" 状态以维持历史可追溯（资料来源：src/mnemo/domain/memory.py:24-55）。

检索请求：双轨混合排序

mnemo 的检索不是纯语义、也不是纯 FTS，而是一次双轨的混合排序。请求载体是 Retrieval 数据类，它同时承载 text（FTS 词法腿）与 vector（稠密腿）。__post_init__ 强制不变式：两者要么都提供（一次搜索），要么都不提供（过滤式浏览）；只提供其一会被立即拒绝并附明确错误——因为只用一半信号排序几乎总意味着调用方构建请求时漏掉了查询的向量化（资料来源：src/mnemo/application/retrieval.py:18-28）。

SearchCriteria 是与具体后端解耦的过滤规约：scope（project / global / all）、project、type、tags、related_files、created_after。created_after 在构造时即被解析为 datetime 并规范化为 UTC——这是因为域内的 created_at 始终是 UTC ISO 字符串，存储层依赖字符串比较排序，提前归一化可同时保证进程内匹配器与 SQL >= 子句行为一致（资料来源：src/mnemo/application/search_criteria.py:25-38）。

浏览模式：无查询的过滤读取

BrowseMemoryUseCaseImpl 提供"按过滤条件列出最近记忆"的语义——它的请求体 Retrieval 中 text 与 vector 均为 None，因此不进入任何相关性排序。结果按 created_at 倒序返回，且不带分数字段。返回的 BrowseResult 是面向客户端的精简视图（id / type / scope / project / content / related_files / created_at），刻意省略 tags、topic_key、session_id 等内部字段以减小线缆体积（资料来源：src/mnemo/application/use_cases/browse_memory.py:1-30）。

MCP 层的 browse 工具在文档中明确推荐用于"按类型/时间分类检索"的场景，因为此场景下语义查询只会带来无意义的偏序。

Recall 流水线：分阶段的数据流

v0.3.0 引入的 recall 是 mnemo 中唯一可选的 LLM 读取工具。它的产物是 RecallBundle：RecallSection 元组（按 type 分组），加一个可选的 summary——后者仅当生成器阶段实际运行时填充，否则分组与顺序本身就承载结构（资料来源：src/mnemo/application/recall/bundle.py:11-30）。

GatherStage 是流水线的相关性步骤——它复用了 search 的同一条混合检索路径（嵌入查询 → 稠密 + 词法），并把范围固定在"命名项目 + 全局记忆"内，上限为请求中的 limit（资料来源：src/mnemo/application/recall/gather_stage.py:18-35）。AssembleStage 是纯分组阶段、不涉及任何模型调用，它将 GATHERED 按 memory.type.value 聚合为有序的 RecallSection 元组，为后续可选的生成器提供结构化输入（资料来源：src/mnemo/application/recall/assemble_stage.py:12-25）。

CLI 与 MCP 同时暴露这一入口：mnemo recall <project> <query> 与 recall MCP 工具共用 RecallProjectUseCaseImpl.execute()。当生成器关闭时，RecallBundle 仅承载分组与顺序本身；当生成器启用时，Gemma 4 E2B-it（QAT GGUF）会基于这些分组合成简洁、基于证据的回答，并在无相关记忆时回复 No relevant memories found.——它绝不会越过记忆库引入外部知识。模型时延与 RAM 信息由 MNEMO_LOG_LEVEL 控制送往日志，最终结构以 JSON 输出到终端（资料来源：README.md:1-20, src/mnemo/application/use_cases/recall_project.py:18-40, src/mnemo/adapters/cli/app.py:60-90）。

嵌入器的选择同样会影响所有上述操作的存储与召回质量：hash 嵌入器是确定性的、零依赖的占位实现（仅捕获词袋重叠、不具备语义能力），适合离线测试；生产路径默认走 pplx（pplx-embed-v1-0.6b 的 int8 ONNX，通过 llmkit 在 CPU 上推理），由 composition._build_embedder() 集中切换（资料来源：src/mnemo/adapters/embedding/hash_embedder.py:10-35, src/mnemo/infrastructure/composition.py:55-90）。

配置体系

mnemo 的运行时参数来源于两层：进程级环境变量与客户机自己的 JSON 配置文件。这两层在 composition root 汇合，最终冻结成一个不可变的依赖图。

`Config` 与环境变量

Config dataclass 描述一个可启动的 mnemo 实例所需的所有字段，包括数据目录、嵌入器名称、Recall 阶段的 rerank / generate 模型选择及其 tokens 上限。它由 src/mnemo/infrastructure/config.py 从环境变量读取，例如 MNEMO_EMBEDDER、MNEMO_GENERATOR、MNEMO_RERANKER、MNEMO_LOG_LEVEL 等。日志子系统单独由 src/mnemo/infrastructure/logging_config.py 暴露，配置加载与日志初始化解耦。

模型描述（llmkit）

外置模型的"在哪里、以何种生命周期加载"由 ModelConfig 描述，见 src/llmkit/config.py。它把 OnnxSource / GgufSource 与 Residency 策略封装在一起，由消费者（mnemo）自行构造并传入 llmkit.build，而不是从环境变量解析——生命周期策略被视为代码侧决策，不暴露给运维。

JSON 配置文件读写

为避免破坏 Cursor / Claude Desktop 等客户机自己的 JSON 配置，src/mnemo/adapters/setup/json_config.py 提供最小化的 load_json / save_json：保留未知键、不重排顺序，文件缺失或为空时返回空字典，写入时附加换行符以利于版本控制 diff。

客户端安装器（Client Installer）

不同 AI 代理客户端拥有各自专属的接入方式，但统一通过一个端口（port）暴露，使调用者不必关心实现差异。

安装器协议

src/mnemo/adapters/setup/client_installer.py 定义了 ClientInstaller Protocol，包含三个动作：detect() 判断客户端是否在本机安装；describe() 返回一行可读的接线说明（用于 --dry-run 与交互提示）；install() 实际写入配置并返回 InstallResult。所有实现都向该端口适配。

注册与具体实现

src/mnemo/adapters/setup/client_registry.py 维护 slug → 安装器的注册表，使 mnemo setup <client> 命令按名称查找实现。具体策略遵循"客户机用什么工具，就用什么工具"：

• src/mnemo/adapters/setup/cli_client_installer.py 通过调用客户机官方的 mcp add 子进程完成接线；
• src/mnemo/adapters/setup/mcp_servers_json_installer.py 通过读写 mcp_servers.json 完成接线。

install() 是幂等的——重复运行不会破坏已有配置。

部署入口

composition root

src/mnemo/infrastructure/composition.py 是整个应用的组合根：从 Config 出发构建 SQLite 仓储、项目 gate、嵌入器（hash 或 pplx）、调度器、session_provider，然后装配出全部 use case 实例（remember、search、browse、recall、create_project 等）。它是 CLI 与 MCP 服务器共享的唯一构造路径，保证两条入口拿到的是同一份依赖图。

CLI 与 MCP 适配器

• CLI：src/mnemo/adapters/cli/app.py 用 Typer 暴露 store / search / browse / recall / setup 等命令，每次调用都重新走一遍 build_container()，因此配置变更无需重启进程外的服务。recall 命令在 reranker / generator 缺失时会把 actionable RuntimeError 直接打到 stderr 而非 traceback。
• MCP 服务器：src/mnemo/adapters/mcp/server.py 把同一组 use case 暴露为 mcp.tool()，包括 remember、search、browse、recall、create_project、update_project、delete_project、list_projects，从而被 Cursor、Claude Desktop 等代理直接发现与调用。

配置与部署流程

flowchart LR
    A[环境变量 MNEMO_*] --> B[Config dataclass]
    B --> C[composition root]
    D[客户机 JSON 配置] --> E[json_config 读写]
    E --> F[ClientInstaller.install]
    F --> G[mcp_servers.json / mcp add CLI]
    C --> H[use cases 容器]
    H --> I[CLI 适配器]
    H --> J[MCP 适配器]
    J --> K[Cursor / Claude Desktop 等]
    I --> L[终端用户]

See Also

• recall 命令 / MCP 工具的相关开关（MNEMO_GENERATOR、MNEMO_RERANKER、MNEMO_LOG_LEVEL）详见 Recall 页面。
• 嵌入器 hash 与 pplx 的取舍详见 Embedding 页面。
• 项目 gate 与 near-match 候选建议见 Project Model 页面。

Pitfall Log / 踩坑日志

项目：arttttt/mnemo

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

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

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

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

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

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

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

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

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

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

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

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

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

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