# https://github.com/Mnemoq/MnemoQ 项目说明书 生成时间：2026-06-27 10:21:47 UTC ## 目录 - [Project Overview & System Architecture](#page-1) - [Core Engine: Retrieval, Validation, and Consolidation](#page-2) - [MCP Server, SDK, and Platform Integration](#page-3) - [Data Schema, Configuration & Deployment](#page-4) ## Project Overview & System Architecture ### 相关页面 相关主题：[Core Engine: Retrieval, Validation, and Consolidation](#page-2), [MCP Server, SDK, and Platform Integration](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/Mnemoq/MnemoQ/blob/main/README.md) - [src/agent_memory/cli.py](https://github.com/Mnemoq/MnemoQ/blob/main/src/agent_memory/cli.py) - [src/agent_memory/mcp_main.py](https://github.com/Mnemoq/MnemoQ/blob/main/src/agent_memory/mcp_main.py) - [src/agent_memory/scaffold.py](https://github.com/Mnemoq/MnemoQ/blob/main/src/agent_memory/scaffold.py) - [src/agent_memory/engine/mcp_server.py](https://github.com/Mnemoq/MnemoQ/blob/main/src/agent_memory/engine/mcp_server.py) - [src/agent_memory/engine/models.py](https://github.com/Mnemoq/MnemoQ/blob/main/src/agent_memory/engine/models.py) - [src/agent_memory/engine/constants.py](https://github.com/Mnemoq/MnemoQ/blob/main/src/agent_memory/engine/constants.py) - [src/agent_memory/engine/handlers.py](https://github.com/Mnemoq/MnemoQ/blob/main/src/agent_memory/engine/handlers.py) - [src/agent_memory/engine/retrieval.py](https://github.com/Mnemoq/MnemoQ/blob/main/src/agent_memory/engine/retrieval.py) - [src/agent_memory/engine/metrics.py](https://github.com/Mnemoq/MnemoQ/blob/main/src/agent_memory/engine/metrics.py) - [src/agent_memory/engine/agents_review.py](https://github.com/Mnemoq/MnemoQ/blob/main/src/agent_memory/engine/agents_review.py) - [src/agent_memory/engine/git_utils.py](https://github.com/Mnemoq/MnemoQ/blob/main/src/agent_memory/engine/git_utils.py) - [src/agent_memory/engine/eval.py](https://github.com/Mnemoq/MnemoQ/blob/main/src/agent_memory/engine/eval.py)
# 项目总览与系统架构 ## 1. 项目定位与核心价值 MnemoQ（Agent Memory Engine，下文简称引擎）是一个为 AI 编码代理设计的**情景记忆（episodic memory）系统**，核心目标是在多步任务中让代理跨会话、跨项目复用过往的踩坑记录、调优经验和架构教训，而不是每次都从零推导。资料来源：[README.md]() 系统围绕一个追加式 JSONL 文件 `learnings.jsonl` 作为唯一权威存储，所有写入路径必须通过同一条校验闸门，避免在多个项目中产生非法或不一致条目。资料来源：[src/agent_memory/engine/constants.py]()。同时，引擎内置了 BM25 检索、指数衰减排序、可选重排序器（`cross-encoder` 或 `llm-local`）以及"睡眠周期"（Sleep Cycle）合并机制，让条目随着时间被自然淘汰、归档或提升。资料来源：[README.md:48-66]() ## 2. 系统架构总览 引擎在分层上遵循"接口层 → 引擎核心 → 持久化"的清晰边界。下图展示了从 CLI / MCP 客户端到磁盘 JSONL 的请求路径： ```mermaid flowchart LR A[CLI / MCP 客户端] --> B[接口层
cli.py / mcp_main.py] B --> C[引擎核心
retrieval / handlers / consolidation] C --> D[持久化层
learnings.jsonl / metrics.jsonl / archive/] C --> E[配置层
config.json + constants.py] C --> F[辅助模块
git_utils / agents_review / eval] D --> G[(磁盘 / Git 仓库)] E --> G F --> C ``` 接口层只负责把外部调用（命令行参数或 MCP JSON-RPC 消息）映射成引擎函数，不做业务校验；引擎核心统一处理解析、检索、校验、写入和合并；持久化层把一切落到 `` 下的标准文件结构。资料来源：[src/agent_memory/cli.py:14-42]()、[src/agent_memory/engine/mcp_server.py:1-18]()。 ## 3. 核心引擎模块 引擎核心由若干职责单一的模块组成，分别对应一条主要的命令路径。 | 模块 | 主要职责 | 关键导出 | |------|---------|---------| | `retrieval.py` | 基于 BM25 的相关性打分 + 时间衰减 + 可选重排序 | `retrieve_core` | | `handlers.py` | 写入、解决、统计三大命令的纯函数实现 | `log_core` / `resolve_core` / `stats_core` | | `metrics.py` | 结构化事件埋点（retrieval/log/update/resolve/consolidate） | `read_metrics` / `_retrieval_stats` 等 | | `agents_review.py` | 解析 `AGENTS.md`，检测学习条目与文档条目的语义冲突 | `check_agents_conflict` | | `git_utils.py` | 自动注入 commit / ts 字段，并基于 `git diff` 检测条目陈旧度 | `stamp_entry` / `check_staleness` | | `eval.py` | 读取 `eval/grading.jsonl` 并跑检索命中率评测 | `run_eval` | 资料来源：[src/agent_memory/engine/retrieval.py]()、[src/agent_memory/engine/handlers.py:1-30]()、[src/agent_memory/engine/metrics.py:1-22]()。 每个核心入口都接受一个 `_Paths` 数据类和 `ctx` 字典，`ctx` 用于在运行时覆盖默认配置（如 `DOMAIN_MAPPINGS`、`tuning` 参数），从而在不重启进程的情况下完成 Phase-2 初始化。资料来源：[src/agent_memory/engine/constants.py:24-32]()。 ## 4. 接口层：CLI 与 MCP 双通道 引擎同时暴露两种调用形式，互为等价但服务于不同的宿主环境。 **CLI 模式** 由 `src/agent_memory/cli.py` 入口 `python -m agent_memory.cli` 触发，支持 `--step/--components/--files/--domain` 检索、`--log` / `--log-file` 写入、`--resolve`、`--stats`、`--consolidate`、`--review-agents`、`--verify` 等子命令。资料来源：[src/agent_memory/cli.py:1-42]()。 **MCP 模式** 通过 `src/agent_memory/mcp_main.py` 启动 stdio 上的 JSON-RPC 服务器，对外暴露 `retrieve_learnings`、`log_learning`、`resolve_learning`、`get_stats`、`consolidate` 五个工具，以及 `learnings://project/{id}` 与 `metrics://project/{id}` 两个资源模板，所有请求体均通过 `pydantic` 模型 `LearningEntry` / `LogRequest` 进行统一校验。资料来源：[src/agent_memory/engine/mcp_server.py:1-36]()、[src/agent_memory/engine/models.py:1-30]()。 两路入口最终都会进入相同的引擎函数（`retrieve_core`、`log_core`、`resolve_core`、`stats_core`、`consolidate_core`），因此业务行为天然一致，避免出现"CLI 写一条、MCP 写一条"行为不一致的情况。 ## 5. 持久化与数据模型 引擎的写入路径只接受符合 `LearningEntry` 模式的 JSON 对象，必填字段包括 `step`、`source_agent`、`type`、`domain`、`components`、`files_touched`、`trigger`、`action`、`reason`、`importance`、`severity`，可选字段则覆盖 `scope`、`verified`、`debt_level`、`embedding`、`project_id` 等扩展维度。资料来源：[src/agent_memory/engine/models.py:11-40]()。 值域白名单集中定义在 `constants.py`：合法 `type` 仅 `bug_fix / optimization / architectural_pattern`，合法 `domain` 12 类，合法 `severity` 为 `minor / major / critical`，`scope` 为 `file / module / system`，`debt_level` 为 `proper / workaround / temporary`。任何不在白名单内的取值都会被校验闸门直接拒收，防止跨项目的字段语义漂移（例如 `feature_request` 在 A 项目被允许但在 B 项目不应被允许）。资料来源：[src/agent_memory/engine/constants.py:1-22]()。 每条条目在落盘前会被 `git_utils.stamp_entry` 自动补齐 `commit`、`ts`、`access_count`、`reinforcement_count`，并在随后的 Sleep Cycle 中通过 `git diff` 重新评估其陈旧度。资料来源：[src/agent_memory/engine/git_utils.py:11-40]()。 ## 6. 运行时配置 `config.json` 提供默认值与可覆盖项的统一入口，README 文档列出了完整字段说明，关键字段包括 `schema_version`、`max_step`、`valid_domains`、`valid_source_agents`、`retrieval_only_agents`、`embedding_model`、`reranker`、`tuning.decay_rate` 等。资料来源：[README.md:30-66]()。初次安装时，`scaffold.py` 会引导用户输入项目名并接受默认 tuning 参数，避免冷启动时手工编辑出错。资料来源：[src/agent_memory/scaffold.py:1-40]()。 ## See Also - [Configuration Reference](configuration-reference.md) - [Retrieval Engine Internals](retrieval-engine.md) - [Sleep Cycle & Consolidation](sleep-cycle.md) - [MCP Server API](mcp-server-api.md) --- ## Core Engine: Retrieval, Validation, and Consolidation ### 相关页面 相关主题：[Project Overview & System Architecture](#page-1), [Data Schema, Configuration & Deployment](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [src/agent_memory/cli.py](https://github.com/Mnemoq/MnemoQ/blob/main/src/agent_memory/cli.py) - [src/agent_memory/engine/handlers.py](https://github.com/Mnemoq/MnemoQ/blob/main/src/agent_memory/engine/handlers.py) - [src/agent_memory/engine/retrieval.py](https://github.com/Mnemoq/MnemoQ/blob/main/src/agent_memory/engine/retrieval.py) - [src/agent_memory/engine/constants.py](https://github.com/Mnemoq/MnemoQ/blob/main/src/agent_memory/engine/constants.py) - [src/agent_memory/engine/models.py](https://github.com/Mnemoq/MnemoQ/blob/main/src/agent_memory/engine/models.py) - [src/agent_memory/engine/consolidation.py](https://github.com/Mnemoq/MnemoQ/blob/main/src/agent_memory/engine/consolidation.py) - [src/agent_memory/engine/git_utils.py](https://github.com/Mnemoq/MnemoQ/blob/main/src/agent_memory/engine/git_utils.py) - [src/agent_memory/engine/metrics.py](https://github.com/Mnemoq/MnemoQ/blob/main/src/agent_memory/engine/metrics.py) - [src/agent_memory/engine/eval.py](https://github.com/Mnemoq/MnemoQ/blob/main/src/agent_memory/engine/eval.py) - [src/agent_memory/engine/mcp_server.py](https://github.com/Mnemoq/MnemoQ/blob/main/src/agent_memory/engine/mcp_server.py) - [src/agent_memory/engine/agents_review.py](https://github.com/Mnemoq/MnemoQ/blob/main/src/agent_memory/engine/agents_review.py) - [README.md](https://github.com/Mnemoq/MnemoQ/blob/main/README.md)
# Core Engine: Retrieval, Validation, and Consolidation ## 概述与架构 MnemoQ 的 **Core Engine** 是 Agent Memory 系统的中枢，负责在多智能体（multi-agent）软件开发场景中提供三类核心能力： 1. **检索 (Retrieval)**：根据任务上下文（`step` / `components` / `files` / `domain`）从 `learnings.jsonl` 中筛选并打分相关学习条目。 2. **验证 (Validation)**：在写入路径上拦截非法条目，保证数据 schema 一致性。 3. **整合 (Consolidation)**：周期性触发 "Sleep Cycle"，归档未解决条目、生成晋级候选、检测矛盾与陈旧条目。 引擎通过同一组 `*_core` 函数同时被 CLI（`src/agent_memory/cli.py`）、HTTP/MCP 服务器（`src/agent_memory/engine/mcp_server.py`）以及 SDK 共享，从而保证多端行为一致 [资料来源：[src/agent_memory/cli.py:1-30]()] [资料来源：[src/agent_memory/engine/mcp_server.py:1-30]()]。下图展示了从任务上下文到经验沉淀的完整生命周期： ```mermaid flowchart LR A["任务上下文
step/components/files/domain"] --> B["检索核心
tiered + BM25 + RRF"] B --> C["重排序器
none / cross-encoder / llm-local"] C --> D["Top-N 学习条目"] E["新学习条目 JSON"] --> F["验证核心
Pydantic + constants 白名单"] F --> G["git_utils.stamp_entry
commit + ts"] G --> H["learnings.jsonl"] H --> I["stats_core
写入 metrics.jsonl"] H --> J["consolidate_core
Sleep Cycle"] J --> K["归档文件 + 晋级报告"] ``` ## 检索机制 (Retrieval) 检索入口是 `retrieve_core(step, components, files, domain, ctx, paths)`，同时被 CLI 的 `--step` 模式与 MCP 工具 `retrieve_learnings` 调用 [资料来源：[src/agent_memory/engine/mcp_server.py:50-60]()]。完整流程分为三阶段： 1. **分层打分 (Tiered Scoring)**：根据 `step` 距离、组件匹配、域匹配为每个候选条目赋初始分。 2. **BM25 评分**：`retrieval.py` 中 `_compute_corpus_stats` 计算文档频率与平均长度，`bm25_score` 实现标准 BM25 公式（带 `k1`、`b` 调参）[资料来源：[src/agent_memory/engine/retrieval.py:1-90]()]。 3. **RRF 融合**：分层排名与 BM25 排名通过 Reciprocal Rank Fusion 合并，公式为 `1 / (rrf_k + rank)`，常数 `rrf_k` 默认 60 [资料来源：[README.md:50-100]()]。 可选的 **Reranker** 在融合之后介入，支持三种模式：`none`、`cross-encoder`、`llm-local`，由 `reranker` 配置字段控制；`reranker_top_n` 控制进入精排的候选数（默认 20）[资料来源：[README.md:30-60]()]。检索质量可通过 `eval.py` 中的 grade harness 进行离线评估，它读取 `memory/eval/grading.jsonl` 并以子进程方式运行检索，输出 top-1 / top-3 命中率 [资料来源：[src/agent_memory/engine/eval.py:1-60]()]。 ## 写入验证 (Validation) 所有写入路径（CLI `--log`、MCP 工具 `log_learning`、HTTP `POST /api/log`）都经过两层校验： 1. **Pydantic Schema**：`LearningEntry` 模型定义必填字段约束——`step >= 1`、`components` / `files_touched` 非空、`trigger` 必须以 "When" 开头、`action` 必须包含 "ALWAYS" 或 "NEVER" 等；`model_config = {"extra": "allow"}` 允许扩展字段 [资料来源：[src/agent_memory/engine/models.py:1-60]()]。 2. **常量白名单**：`constants.py` 维护枚举白名单——`VALID_TYPES = {"bug_fix", "optimization", "architectural_pattern"}`、`VALID_DOMAINS`（包含 `ui` / `data` / `tooling` / `performance` / `testing` / `security` / `api` / `backend` / `frontend` / `database` / `deployment` / `documentation`）、`VALID_SEVERITIES = {"minor", "major", "critical"}`、`VALID_SCOPES = {"file", "module", "system"}`、`VALID_DEBT_LEVELS = {"proper", "workaround", "temporary"}` [资料来源：[src/agent_memory/engine/constants.py:1-30]()]。 通过校验的条目进入 `git_utils.stamp_entry`，自动注入 `commit`（`git rev-parse --short HEAD`）和 ISO-8601 UTC 时间戳 `ts`，并初始化 `access_count = 0`、`reinforcement_count = 0` [资料来源：[src/agent_memory/engine/git_utils.py:1-40]()]。`config.json` 中的 `valid_domains` / `valid_source_agents` / `retrieval_only_agents`（仅 `basic-reviewer`）等字段允许进一步收紧白名单 [资料来源：[README.md:20-50]()]。 ## 整合与睡眠周期 (Consolidation) Consolidation 又称 **Sleep Cycle**，由 `consolidate_core` 实现，可通过 CLI 参数 `--consolidate [--sprint N]` 或 MCP 工具 `consolidate` 触发；后者还支持 `force` 参数以覆盖已存在的归档 [资料来源：[src/agent_memory/cli.py:20-40]()] [资料来源：[src/agent_memory/engine/mcp_server.py:80-100]()]。其职责包括： - **归档未解决条目**：将 unresolved 学习写入按 sprint 编号命名的归档文件。 - **生成晋级候选**：从高频强化（`reinforcement_count`）条目中提炼值得晋升到 `AGENTS.md` 的规则。 - **检测矛盾**：跨条目比较相同 `trigger` 与相反 `action`。 - **检测陈旧**：`git_utils.check_staleness` 通过 `git diff` 对比 `commit` 与当前 HEAD 之间 `files_touched` 的行变化 [资料来源：[src/agent_memory/engine/git_utils.py:40-70]()]。 触发时机由 `tuning.sleep_cycle_days`（默认 7 天）与 `tuning.sleep_cycle_quarantine_threshold`（默认 20）共同决定；`stats_core` 会预判 `sleep_cycle_due` 状态并返回 `sleep_cycle_reasons` [资料来源：[src/agent_memory/engine/handlers.py:1-50]()]。CLI 还提供 `--consolidate --confirm-reset`，在确认归档后可清空 `learnings.jsonl` [资料来源：[src/agent_memory/cli.py:25-40]()]。 ## 配置调优、指标与诊断 所有引擎调用都会向 `/metrics.jsonl` 追加结构化事件，事件类型包括 `retrieval`、`log`、`update`、`resolve`、`stats`、`consolidate`、`review_agents`，每条都带 `ts`、`project_id`、`latency_ms` 等公共字段，可跨项目（`~/.agent-memory/engine/projects.txt` 列举）聚合分析 [资料来源：[src/agent_memory/engine/metrics.py:1-40]()]。`stats_core` 汇总总量、未解决 / 已解决比例、严重度 / 类型 / 域分布、强化模式与睡眠周期状态 [资料来源：[src/agent_memory/engine/handlers.py:1-50]()]。 常用调优字段（见 README 配置表）：`tuning.decay_rate = 0.995`（按 step 的指数衰减）、`tuning.score_threshold = 0.15`（最小检索分数）、`tuning.embedding_alpha = 0.5`（RRF 与 cosine 融合权重）、`tuning.semantic_dedup_threshold = 0.85`（去重相似度）、`tuning.bm25_k1 = 1.5`、`tuning.bm25_b = 0.75` [资料来源：[README.md:50-100]()]。此外，`agents_review.py` 提供 `--review-agents` 诊断模式：通过 Jaccard 相似度 + 关键词包含数（阈值 `>= 0.1` 或 `>= 3` 命中）评估 `AGENTS.md` 章节健康度，将每节标记为 ACTIVE / COLD / UNMATCHED [资料来源：[src/agent_memory/engine/agents_review.py:60-110]()]。 ## See Also - [README.md](https://github.com/Mnemoq/MnemoQ/blob/main/README.md) — 项目总览、配置参考与数据 schema - [CHANGELOG.md](https://github.com/Mnemoq/MnemoQ/blob/main/CHANGELOG.md) — 版本变更记录 - [docs/ROADMAP.md](https://github.com/Mnemoq/MnemoQ/blob/main/docs/ROADMAP.md) — 路线图与计划功能 - [CONTRIBUTING.md](https://github.com/Mnemoq/MnemoQ/blob/main/CONTRIBUTING.md) — 贡献流程与 CLA --- ## MCP Server, SDK, and Platform Integration ### 相关页面 相关主题：[Project Overview & System Architecture](#page-1), [Core Engine: Retrieval, Validation, and Consolidation](#page-2)
相关源码文件 以下源码文件用于生成本页说明： - [src/agent_memory/engine/mcp_server.py](https://github.com/Mnemoq/MnemoQ/blob/main/src/agent_memory/engine/mcp_server.py) - [src/agent_memory/mcp_main.py](https://github.com/Mnemoq/MnemoQ/blob/main/src/agent_memory/mcp_main.py) - [src/agent_memory/sdk/client.py](https://github.com/Mnemoq/MnemoQ/blob/main/src/agent_memory/sdk/client.py) - [src/agent_memory/sdk/__init__.py](https://github.com/Mnemoq/MnemoQ/blob/main/src/agent_memory/sdk/__init__.py) - [src/agent_memory/sdk/exceptions.py](https://github.com/Mnemoq/MnemoQ/blob/main/src/agent_memory/sdk/exceptions.py) - [src/agent_memory/scaffold.py](https://github.com/Mnemoq/MnemoQ/blob/main/src/agent_memory/scaffold.py) - [src/agent_memory/cli.py](https://github.com/Mnemoq/MnemoQ/blob/main/src/agent_memory/cli.py) - [src/agent_memory/engine/models.py](https://github.com/Mnemoq/MnemoQ/blob/main/src/agent_memory/engine/models.py) - [src/agent_memory/engine_version.py](https://github.com/Mnemoq/MnemoQ/blob/main/src/agent_memory/engine_version.py) - [README.md](https://github.com/Mnemoq/MnemoQ/blob/main/README.md)
# MCP Server、SDK 与平台集成 ## 概述 MnemoQ 是一个面向 AI Agent 的本地优先（local-first）记忆引擎，其核心交付形态围绕模型上下文协议（Model Context Protocol, MCP）展开。系统通过标准化的 JSON-RPC 接口、共享的 Pydantic 数据模型与脚手架工具，使 Claude Desktop、Cursor、Windsurf、VS Code 等多种 Agent 客户端能够以一致的方式记录（log）、检索（retrieve）与整合（consolidate）学习条目。README 中明确提到，MCP 集成覆盖所有兼容 MCP 的客户端，并通过 stdio 通道提供 JSON-RPC 服务，无需 FastAPI/uvicorn 等额外 Web 框架依赖。资料来源：[README.md:11-15]() ## MCP 服务器架构 ### 工具与资源 `agent_memory/engine/mcp_server.py` 是 MCP 服务器的核心实现。该模块基于 Python 标准库构建 JSON-RPC over stdio，仅依赖 pydantic 进行参数校验，因此部署时无需引入 Web 容器。其对外暴露的能力分为两类： - **工具（Tools）**：包括 `retrieve_learnings(step, components, files, domain)`、`log_learning(entry)`、`resolve_learning(timestamp)`、`get_stats()` 与 `consolidate(sprint_number, force=False)`。其中 `consolidate` 即"睡眠周期"（Sleep Cycle），负责归档未解决条目、生成晋升候选、检测矛盾并检查陈旧条目。资料来源：[src/agent_memory/engine/mcp_server.py:25-95]() - **资源（Resources）**：通过 URI 模板暴露 `learnings://project/{project_id}` 与 `metrics://project/{project_id}`，分别返回项目的所有学习条目和指标摘要。资料来源：[src/agent_memory/engine/mcp_server.py:79-95]() ### 工具分发与路径解析 `_call_tool()` 是统一的工具调用路由器，根据 `name` 字段将请求分派给底层的核心函数（`retrieve_core`、`log_core`、`resolve_core`、`stats_core`、`consolidate_core`），并把结果以 `content[].text` 形式回传。每个工具都使用相同的 `_Paths` 数据类（包含 `memory_dir`、`repo_root`、`config_path`、`learnings_path` 等字段）来定位项目资源。资料来源：[src/agent_memory/engine/mcp_server.py:42-78]() ```mermaid flowchart LR Client[Agent / MCP 客户端] -->|stdio JSON-RPC| MCPServer[mnemoq-mcp] MCPServer -->|retrieve_learnings| RetrieveCore[retrieve_core] MCPServer -->|log_learning| LogCore[log_core] MCPServer -->|resolve_learning| ResolveCore[resolve_core] MCPServer -->|get_stats| StatsCore[stats_core] MCPServer -->|consolidate| ConsolidateCore[consolidate_core] RetrieveCore --> JSONL[(learnings.jsonl)] LogCore --> JSONL ConsolidateCore --> Archive[archive 目录] MCPServer -->|读指标| Metrics[metrics.jsonl] ``` ### 入口与启动方式 入口脚本 `mcp_main.py` 解析 `--memory-dir` 命令行参数后调用 `run_server(memory_dir)`。若未提供该参数，则会读取 `AGENT_MEMORY_DIR` 环境变量或在工作目录下自动发现 `memory/` 目录。CLI 中也提供了等价的 `--mcp` 标志来启动同一服务器，但该标志与其它操作型标志（如 `--step`、`--log`、`--verify`）互斥，混合使用会被 `parser.error()` 拒绝。资料来源：[src/agent_memory/mcp_main.py:1-25]()、[src/agent_memory/cli.py:227-247]() ## SDK 与共享数据模型 ### 单一可信模式源 `agent_memory/engine/models.py` 定义了跨 HTTP 服务器、MCP 服务器与 SDK 共享的请求/响应模式，确保所有接入层使用单一可信数据源。其中 `LearningEntry` 是核心条目模式，必填字段包括 `step`、`source_agent`、`type`、`domain`、`components`（至少 1 个）、`files_touched`（至少 1 个）、`trigger`、`action`、`reason`、`importance`（1–10）和 `severity`，并通过 `Field(ge=, le=)` 约束取值范围；可选字段涵盖 `scope`、`verified`、`symptoms`、`debt_level` 等。`LogRequest` 与 `UpdateRequest` 则分别对应 `POST /api/log` 与 `POST /api/update` 的请求体。资料来源：[src/agent_memory/engine/models.py:1-50]() ### CLI 互斥与可选依赖 CLI 通过 `argparse` 强制实施互斥规则——例如 `--mcp`、`--verify`、`--migrate_schema` 都不能与其它操作型标志共存；而 `--serve` / `--dashboard` 模式需要 `[api]` 可选依赖（uvicorn），未安装时会打印 `pip install agent-memory[api]` 提示并返回退出码 1。资料来源：[src/agent_memory/cli.py:236-247]() ## 平台集成与脚手架 ### IDE 平台支持 `scaffold.py` 提供 `mnemoq-scaffold` 命令，在目标项目中创建 `memory/` 目录并写入 `config.json` 与 `learnings.jsonl`。其 `--ide` 参数支持多种 Agent 平台：`opencode`、`windsurf`、`cursor`、`claude-code`、`copilot`，并可通过 `--ide all` 一键启用全部，或通过 `--ide ?` 查询支持的列表。资料来源：[src/agent_memory/scaffold.py:1-150]()、[README.md:32-44]() ### Shim 与版本回退 `scaffold.py` 在写入项目记忆目录时会先删除遗留的 `profile.py`，然后写入一个轻量级 shim 文件 `filter.py` 作为对 `agent_memory` 包的转发层。这意味着主仓库更新时只需升级已安装的 Python 包即可，无需手动同步引擎文件。资料来源：[src/agent_memory/scaffold.py:74-95]() 版本号由 `engine_version.py` 中的 `get_engine_version()` 提供，采用三层回退链：先查询已安装的 `mnemoq` 包元数据，再读取本地 `VERSION` 文件，最后回退到硬编码的 `FALLBACK_VERSION`，从而在开发与部署环境中都能正确报告引擎版本。资料来源：[src/agent_memory/engine_version.py:1-30]() ## 常见故障模式 | 现象 | 触发条件 | 解决方式 | |------|---------|---------| | 路径解析失败 | 未设置 `AGENT_MEMORY_DIR` 且 `memory/` 不在 cwd | 通过 `--memory-dir` 显式指定 | | 标志冲突 | `--mcp` 或 `--verify` 与其它操作型标志混用 | `parser.error()` 拒绝，需拆分为两次调用 | | 依赖缺失 | 启用 `--serve` / `--dashboard` 但未安装 `agent-memory[api]` | `pip install agent-memory[api]` | | shim 已存在 | `filter.py` 已是 shim 且未传 `--force` | 跳过写入，幂等 | ## See Also - [CLI Reference](https://github.com/Mnemoq/MnemoQ/blob/main/docs/cli-reference.md) - [MCP Integration Guide](https://github.com/Mnemoq/MnemoQ/blob/main/docs/mcp-integration.md) - [Configuration Tuning](https://github.com/Mnemoq/MnemoQ/blob/main/docs/config-tuning.md) - [Architecture Documentation Index](https://github.com/Mnemoq/MnemoQ/blob/main/docs/README.md) --- ## Data Schema, Configuration & Deployment ### 相关页面 相关主题：[Core Engine: Retrieval, Validation, and Consolidation](#page-2), [MCP Server, SDK, and Platform Integration](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/Mnemoq/MnemoQ/blob/main/README.md) - [src/agent_memory/engine/constants.py](https://github.com/Mnemoq/MnemoQ/blob/main/src/agent_memory/engine/constants.py) - [src/agent_memory/engine/models.py](https://github.com/Mnemoq/MnemoQ/blob/main/src/agent_memory/engine/models.py) - [src/agent_memory/engine/mcp_server.py](https://github.com/Mnemoq/MnemoQ/blob/main/src/agent_memory/engine/mcp_server.py) - [src/agent_memory/engine/eval.py](https://github.com/Mnemoq/MnemoQ/blob/main/src/agent_memory/engine/eval.py) - [src/agent_memory/scaffold.py](https://github.com/Mnemoq/MnemoQ/blob/main/src/agent_memory/scaffold.py) - [src/agent_memory/engine/git_utils.py](https://github.com/Mnemoq/MnemoQ/blob/main/src/agent_memory/engine/git_utils.py)
# Data Schema, Configuration & Deployment 本页聚焦 MnemoQ 引擎的三大基础支柱：学习条目的数据模式、`config.json` 配置项、以及项目的脚手架与部署流程。所有内容均基于仓库源码，描述字段、字段校验、配置默认值以及一键部署方式。 ## 一、学习条目数据模式 (Data Schema) MnemoQ 中的每一条学习记录 (learning entry) 必须满足最低字段约束，必填字段及其校验规则如下： | 字段 | 类型 | 约束 | |---|---|---| | `step` | `int` | ≥ 1 | | `source_agent` | `str` | 取自 `VALID_SOURCE_AGENTS` 白名单 | | `type` | `str` | `bug_fix` / `optimization` / `architectural_pattern` | | `domain` | `str` | 12 个合法域之一（`ui`/`data`/`tooling` 等） | | `components` | `list[str]` | 非空 | | `files_touched` | `list[str]` | 非空 | | `trigger` | `str` | 必须以 `When` 开头 | | `action` | `str` | 必须包含 `ALWAYS` 或 `NEVER` | | `reason` | `str` | 非空 | | `importance` | `int` | 1–10 | | `severity` | `str` | `minor`/`major`/`critical` | 资料来源：[README.md:106-119]() 中给出了简明表格；校验常量定义于 [src/agent_memory/engine/constants.py:8-15]()，其中 `VALID_TYPES`、`VALID_DOMAINS`、`VALID_SEVERITIES` 等枚举集合被验证器直接消费。Pydantic 模型 [`LearningEntry`](src/agent_memory/engine/models.py:18-43) 进一步把这些约束形式化为类型安全对象，被 HTTP 服务、MCP 服务与 SDK 共用，实现"单一数据源"。 引擎在写入 (`log`) 时会自动补齐以下字段，无需用户填写： - `ts`：UTC ISO-8601 时间戳，由 [src/agent_memory/engine/git_utils.py:13-39]() 的 `stamp_entry()` 通过 `datetime.now(timezone.utc)` 生成； - `commit`：调用 `git rev-parse --short HEAD` 获取短哈希； - `access_count` 与 `reinforcement_count`：默认 0； - `schema_version`：默认 1； - 溯源字段：`project_id`、`origin_project` 等。 ## 二、配置文件 (config.json) `memory/config.json` 控制引擎行为，由 `mnemoq-scaffold --defaults` 自动生成，主要选项如下： | Key | 默认值 | 含义 | |---|---|---| | `engine_version` | `"1.15.0"` | 最低引擎版本要求 | | `schema_version` | `1` | 配置 schema 版本 | | `max_step` | `null` | step 上限（`null` 表示无限制） | | `valid_domains` | `null` | 自定义域白名单（覆盖内置值） | | `valid_source_agents` | `null` | 自定义 agent 白名单 | | `retrieval_only_agents` | `null` | 仅可检索、不可写入的 agent 列表 | | `domain_mappings` | `null` | 自定义域→规范标签映射 | | `api_key` | `null` | HTTP API 鉴权密钥（`null` 表示无鉴权） | | `embedding_model` | `"all-MiniLM-L6-v2"` | sentence-transformers 模型 | | `embedding_cache_dir` | `"~/.agent-memory/models/"` | 模型缓存目录 | | `reranker` | `"none"` | 重排模式：`none` / `cross-encoder` / `llm-local` | | `reranker_top_n` | `20` | 重排前 N 个候选 | | `tuning.decay_rate` | `0.995` | 每 step 指数衰减（时效性） | | `tuning.score_threshold` | `0.15` | 检索最低分阈值 | 资料来源：[README.md:60-86]() 列出了完整的配置项表。`DOMAIN_MAPPINGS` 在 [src/agent_memory/engine/constants.py:30-34]() 采用"两阶段初始化"：模块加载时为 `None`，运行期由 `load_config()` 通过 `ctx` 字典覆盖，实现项目级自定义域映射与硬编码默认值的共存。 ## 三、MCP / HTTP 服务接口 引擎同时暴露 MCP 协议 (stdio) 与 HTTP API 两种接口。`mcp_server.py` 注册了 5 个工具与 2 个资源模板： - **工具**：`retrieve_learnings`、`log_learning`、`resolve_learning`、`get_stats`、`consolidate`； - **资源**：`learnings://project/{project_id}`、`metrics://project/{project_id}`。 MCP 工具的入参由 Pydantic 校验，类型定义复用 [src/agent_memory/engine/models.py:46-55]() 的 `LogRequest` 等模型。`log_learning` 的 `entry` 子对象严格遵循上文数据模式字段，因此 MCP 与 HTTP 通道共享同一份语义约束。资料来源：[src/agent_memory/engine/mcp_server.py:42-118]() 完整展示了工具分派与 JSON Schema。 ```mermaid flowchart LR A[Agent / IDE] -->|JSON-RPC| B(MCP Server) A -->|HTTP| C(HTTP Server) B --> D[Pydantic Models] C --> D D --> E[Validation] E --> F[(learnings.jsonl)] E --> G[(metrics.jsonl)] ``` ## 四、部署与脚手架 (Deployment) ### 4.1 安装 两种官方分发渠道： ```bash pip install mnemoq # 适用于已有 Python 项目 pipx install mnemoq # CLI 独立环境（无需 Python 项目） ``` 资料来源：[README.md:14-22]()。 ### 4.2 项目初始化 `mnemoq-scaffold` 一键生成 `memory/` 目录、`config.json`、`learnings.jsonl`，并把项目注册到 `~/.agent-memory/engine/projects.txt`，随后自动写入 IDE 平台配置： ```bash mnemoq-scaffold ./my-project --defaults mnemoq-scaffold ./my-project --defaults --ide windsurf mnemoq-scaffold ./my-project --defaults --ide windsurf,cursor,claude-code mnemoq-scaffold ./my-project --defaults --ide all mnemoq-scaffold --ide ? # 查看所有支持的 IDE ``` 支持的 IDE：`opencode`、`windsurf`、`cursor`、`claude-code`、`copilot`、`all`。脚手架逻辑见 [src/agent_memory/scaffold.py:101-148]()：若 `config.json` 已存在则跳过，若目标 IDE 未知则报错并列出合法值。 ### 4.3 评估与回填 仓库附带 `mnemoq --eval` 评分脚本，从 `memory/eval/grading.jsonl` 加载 `(step, components, files, domain, expected_trigger)` 夹具，逐条调用 CLI 检索并报告 top-1 / top-3 命中率。该脚本通过 `subprocess` 调用 `python -m agent_memory.cli`，确保每个夹具都加载自身 `config.json`。资料来源：[src/agent_memory/engine/eval.py:35-79]()。 ## 五、常见失败模式 1. **未知 IDE 平台**：脚手架会以非零退出码终止，并在 stderr 打印合法平台列表。 2. **域不在白名单**：当 `valid_domains` 非空且 `domain` 未命中时，记录被写入 `quarantine.jsonl`，不进入 `learnings.jsonl`。 3. **agent 无写权限**：`retrieval_only_agents`（默认 `basic-reviewer`）仅允许检索，写入会触发校验失败。 4. **Git 不可用**：若仓库非 Git 仓库，`stamp_entry()` 会把 `commit` 设为 `"unknown"`，但不会阻断写入；参见 [src/agent_memory/engine/git_utils.py:13-25]()。 ## See Also - 架构总览：[README.md](https://github.com/Mnemoq/MnemoQ/blob/main/README.md) - 检索算法 BM25：[src/agent_memory/engine/retrieval.py](https://github.com/Mnemoq/MnemoQ/blob/main/src/agent_memory/engine/retrieval.py) - 整合/睡眠周期：[src/agent_memory/engine/consolidation.py](https://github.com/Mnemoq/MnemoQ/blob/main/src/agent_memory/engine/consolidation.py) - 指标与监控：[src/agent_memory/engine/metrics.py](https://github.com/Mnemoq/MnemoQ/blob/main/src/agent_memory/engine/metrics.py) --- --- ## Doramagic 踩坑日志 项目：Mnemoq/MnemoQ 摘要：发现 8 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。 ## 1. 配置坑 · 可能修改宿主 AI 配置 - 严重度：medium - 证据强度：source_linked - 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。 - 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。 - 证据：capability.host_targets | https://github.com/Mnemoq/MnemoQ | 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/Mnemoq/MnemoQ | README/documentation is current enough for a first validation pass. ## 3. 运行坑 · 运行可能依赖外部服务 - 严重度：medium - 证据强度：source_linked - 发现：项目说明出现 external service/cloud/webhook/database 等运行依赖关键词。 - 对用户的影响：本地安装成功不等于能力可用，外部服务不可用会阻断体验。 - 证据：packet_text.keyword_scan | https://github.com/Mnemoq/MnemoQ | matched external service / cloud / webhook / database keyword ## 4. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 证据：evidence.maintainer_signals | https://github.com/Mnemoq/MnemoQ | last_activity_observed missing - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 证据：downstream_validation.risk_items | https://github.com/Mnemoq/MnemoQ | no_demo; severity=medium ## 6. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 证据：risks.scoring_risks | https://github.com/Mnemoq/MnemoQ | no_demo; severity=medium ## 7. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 证据：evidence.maintainer_signals | https://github.com/Mnemoq/MnemoQ | issue_or_pr_quality=unknown ## 8. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 证据：evidence.maintainer_signals | https://github.com/Mnemoq/MnemoQ | release_recency=unknown