# mnemos - Doramagic AI Context Pack

> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。

## 充分原则

- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。
- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。

## 给宿主 AI 的使用方式

你正在读取 Doramagic 为 mnemos 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。

## Claim 消费规则

- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。
- **事实最低状态**：`supported`
- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。
- `weak`：只能作为低置信度线索，必须要求用户继续核实。
- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。
- `unverified`：不得作为事实使用，应明确说证据不足。
- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。

## 它最适合谁

- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0002` supported 0.86

## 它能做什么

- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`QUICKSTART.md`, `README.md` Claim：`clm_0001` supported 0.86

## 怎么开始

- `git clone https://github.com/draca-glitch/Mnemos.git` 证据：`README.md` Claim：`clm_0003` supported 0.86
- `pip install -e .` 证据：`README.md` Claim：`clm_0004` supported 0.86
- `claude mcp add -s user mnemos $(pwd)/venv/bin/mnemos serve` 证据：`README.md` Claim：`clm_0005` supported 0.86
- `pip install mnemos` 证据：`QUICKSTART.md` Claim：`clm_0006` supported 0.86, `clm_0008` supported 0.86
- `claude mcp add -s user mnemos mnemos-mcp` 证据：`QUICKSTART.md` Claim：`clm_0007` supported 0.86
- `pip install mnemos[nli]` 证据：`QUICKSTART.md` Claim：`clm_0008` supported 0.86

## 继续前判断卡

- **当前建议**：需要管理员/安全审批
- **为什么**：继续前可能涉及密钥、账号、外部服务或敏感上下文，建议先经过管理员或安全审批。

### 30 秒判断

- **现在怎么做**：需要管理员/安全审批
- **最小安全下一步**：先跑 Prompt Preview；若涉及凭证或企业环境，先审批再试装
- **先别相信**：工具权限边界不能在安装前相信。
- **继续会触碰**：命令执行、本地环境或项目文件、环境变量 / API Key

### 现在可以相信

- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0002` supported 0.86
- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`QUICKSTART.md`, `README.md` Claim：`clm_0001` supported 0.86
- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0003` supported 0.86

### 现在还不能相信

- **工具权限边界不能在安装前相信。**（unverified）：MCP/tool 类项目通常会触碰文件、网络、浏览器或外部 API，必须真实检查权限和日志。
- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。
- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。
- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。
- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。
- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。
- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。
- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`

### 继续会触碰什么

- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`QUICKSTART.md`, `README.md`
- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`QUICKSTART.md`, `README.md`
- **环境变量 / API Key**：项目入口文档明确出现 API key、token、secret 或账号凭证配置。 原因：如果真实安装需要凭证，应先使用测试凭证并经过权限/合规判断。 证据：`CHANGELOG.md`, `QUICKSTART.md`, `README.md`, `docs/usage.md` 等
- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。

### 最小安全下一步

- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）
- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）
- **不要使用真实生产凭证**：环境变量/API key 一旦进入宿主或工具链，可能产生账号和合规风险。（适用：出现 API、TOKEN、KEY、SECRET 等环境线索时。）
- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）

### 退出方式

- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。
- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。
- **准备撤销测试 API key 或 token**：测试凭证泄露或误用时，可以快速止损。
- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。

## 哪些只能预览

- 解释项目适合谁和能做什么
- 基于项目文档演示典型对话流程
- 帮助用户判断是否值得安装或继续研究

## 哪些必须安装后验证

- 真实安装 Skill、插件或 CLI
- 执行脚本、修改本地文件或访问外部服务
- 验证真实输出质量、性能和兼容性

## 边界与风险判断卡

- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0009` inferred 0.45
- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`QUICKSTART.md`, `README.md` Claim：`clm_0010` supported 0.86
- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。
- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。
- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。

## 开工前工作上下文

### 加载顺序

- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。
- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。
- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。
- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。
- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。

### 任务路由

- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`QUICKSTART.md`, `README.md` Claim：`clm_0001` supported 0.86

### 上下文规模

- 文件总数：91
- 重要文件覆盖：40/91
- 证据索引条目：76
- 角色 / Skill 条目：17

### 证据不足时的处理

- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。
- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。
- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。
- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。

## Prompt Recipes

### 适配判断

- 目标：判断这个项目是否适合用户当前任务。
- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。

```text
请基于 mnemos 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。
```

### 安装前体验

- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。
- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。

```text
请把 mnemos 当作安装前体验资产，而不是已安装工具或真实运行环境。

请严格输出四段：
1. 先问我 3 个必要问题。
2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。
3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。
4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。

硬性边界：
- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。
- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。
- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。
- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。
- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。
- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。

```

### 角色 / Skill 选择

- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。
- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。

```text
请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。
```

### 风险预检

- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。
- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。

```text
请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。
```

### 宿主 AI 开工指令

- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。
- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。

```text
请基于 mnemos 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。
```

## 角色 / Skill 索引

- 共索引 17 个角色 / Skill / 项目文档条目。

- **Mnemos**（project_doc）：The last memory you'll ever need. A persistent memory system for AI agents. Named after Mnemosyne Greek: μνήμη, memory . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`
- **Mnemos Benchmarks**（project_doc）：Reproducible benchmarks of Mnemos across multiple public datasets and Mnemos-specific quality measurements. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`benchmarks/README.md`
- **Mnemos Architecture**（project_doc）：1. A memory system should be a memory. It stores data and retrieves it. That is the entire job. No LLM in the retrieval or storage pipeline. The agent thinks; Mnemos remembers. 2. CML is a language, not a compression algorithm. Condensed Memory Language is a token-minimal notation the agent writes directly. It is not compressed or encoded; it is just denser English with structural prefixes and operators. Both humans… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/ARCHITECTURE.md`
- **Agent instructions for Mnemos**（project_doc）：This file is an example of what to put in your AI client's project-level system-prompt file CLAUDE.md for Claude Code, .cursorrules for Cursor, custom-instructions field for Claude Desktop, etc. to get proactive, high-quality use of the Mnemos MCP tools. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/agent-instructions.md`
- **Benchmarks**（project_doc）：Multiple metric classes, clearly separated. Per-mode methodology, LoCoMo, end-to-end QA, consolidation quality, CML fidelity. See comparison.md comparison.md for cross-system comparison tables. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/benchmarks.md`
- **CML: token-minimal memory format**（project_doc）：Condensed Memory Language. A soft convention for writing memories denser, not a parser or a compressor. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/cml.md`
- **How Mnemos compares**（project_doc）：Architecture and benchmark comparisons against MemPalace and the broader memory-system field. See origin.md origin.md for why this comparison exists at all. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/comparison.md`
- **English-primary stores**（project_doc）：Since v10.15.0 the recommended convention for Mnemos stores is English-primary content: the storing agent writes memories in English regardless of the conversation language, keeping verbatim quotes and canonical terms in their original language. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/english-primary.md`
- **Features**（project_doc）：Reference for what's in the box. Architecture-deep details live in ARCHITECTURE.md ARCHITECTURE.md ; design rationale in philosophy.md philosophy.md . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features.md`
- **Origin**（project_doc）：Why Mnemos exists, why the name, and why v10 in a brand-new repository. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/origin.md`
- **Philosophy**（project_doc）：A memory system should be a memory. Not an agent, not a reasoning palace. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/philosophy.md`
- **Session Hooks**（project_doc）：Mnemos is designed to inject memory context into an AI session automatically. Most MCP clients Claude Code, Cursor, etc. support hook-style commands that fire on session lifecycle events. Wiring Mnemos into those hooks turns briefing and prime into no-effort background behavior. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/session-hooks.md`
- **Usage**（project_doc）：Install, register with an MCP client, run from the CLI, configure the optional Nyx cycle. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/usage.md`
- **Mnemos 10.17.0: Zero-LLM Daily Consolidation Cycle**（project_doc）：Mnemos 10.17.0: Zero-LLM Daily Consolidation Cycle 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/plans/2026-07-03-zero-llm-daily-cycle.md`
- **Changelog**（project_doc）：All notable changes to Mnemos. Dates are from the original private development repository, where the system existed under an internal name agent-memory before being open-sourced as Mnemos in this repo. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CHANGELOG.md`
- **Mnemos Quickstart**（project_doc）：Five-minute walkthrough. For the full story architecture, benchmarks, CML, Nyx cycle, storage backends read README.md README.md after this. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`QUICKSTART.md`
- **Roadmap**（project_doc）：Loose, opinionated, subject to change. Not a release schedule. Items move to CHANGELOG.md when shipped. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`ROADMAP.md`

## 证据索引

- 共索引 76 条证据。

- **Mnemos**（documentation）：The last memory you'll ever need. A persistent memory system for AI agents. Named after Mnemosyne Greek: μνήμη, memory . 证据：`README.md`
- **Mnemos Benchmarks**（documentation）：Reproducible benchmarks of Mnemos across multiple public datasets and Mnemos-specific quality measurements. 证据：`benchmarks/README.md`
- **Mnemos Architecture**（documentation）：1. A memory system should be a memory. It stores data and retrieves it. That is the entire job. No LLM in the retrieval or storage pipeline. The agent thinks; Mnemos remembers. 2. CML is a language, not a compression algorithm. Condensed Memory Language is a token-minimal notation the agent writes directly. It is not compressed or encoded; it is just denser English with structural prefixes and operators. Both humans and LLMs read it without decoding. Prose that slips through is shaped into CML at store/ingest time cemelify , not by the Nyx cycle: since v10.20.0 the cycle never rewrites already-stored content in place. 3. Retrieval is configurable, not fixed. Four modes, two flags: BM25 + ve… 证据：`docs/ARCHITECTURE.md`
- **License**（source_file）：Copyright c 2026 Mikael Wedlund draca-glitch 证据：`LICENSE`
- **Agent instructions for Mnemos**（documentation）：This file is an example of what to put in your AI client's project-level system-prompt file CLAUDE.md for Claude Code, .cursorrules for Cursor, custom-instructions field for Claude Desktop, etc. to get proactive, high-quality use of the Mnemos MCP tools. 证据：`docs/agent-instructions.md`
- **Benchmarks**（documentation）：Multiple metric classes, clearly separated. Per-mode methodology, LoCoMo, end-to-end QA, consolidation quality, CML fidelity. See comparison.md comparison.md for cross-system comparison tables. 证据：`docs/benchmarks.md`
- **CML: token-minimal memory format**（documentation）：Condensed Memory Language. A soft convention for writing memories denser, not a parser or a compressor. 证据：`docs/cml.md`
- **How Mnemos compares**（documentation）：Architecture and benchmark comparisons against MemPalace and the broader memory-system field. See origin.md origin.md for why this comparison exists at all. 证据：`docs/comparison.md`
- **English-primary stores**（documentation）：Since v10.15.0 the recommended convention for Mnemos stores is English-primary content: the storing agent writes memories in English regardless of the conversation language, keeping verbatim quotes and canonical terms in their original language. 证据：`docs/english-primary.md`
- **Features**（documentation）：Reference for what's in the box. Architecture-deep details live in ARCHITECTURE.md ARCHITECTURE.md ; design rationale in philosophy.md philosophy.md . 证据：`docs/features.md`
- **Origin**（documentation）：Why Mnemos exists, why the name, and why v10 in a brand-new repository. 证据：`docs/origin.md`
- **Philosophy**（documentation）：A memory system should be a memory. Not an agent, not a reasoning palace. 证据：`docs/philosophy.md`
- **Session Hooks**（documentation）：Mnemos is designed to inject memory context into an AI session automatically. Most MCP clients Claude Code, Cursor, etc. support hook-style commands that fire on session lifecycle events. Wiring Mnemos into those hooks turns briefing and prime into no-effort background behavior. 证据：`docs/session-hooks.md`
- **Usage**（documentation）：Install, register with an MCP client, run from the CLI, configure the optional Nyx cycle. 证据：`docs/usage.md`
- **Mnemos 10.17.0: Zero-LLM Daily Consolidation Cycle**（documentation）：Mnemos 10.17.0: Zero-LLM Daily Consolidation Cycle 证据：`docs/plans/2026-07-03-zero-llm-daily-cycle.md`
- **Init**（source_file）：version = "10.23.1" ⋮---- all = "Mnemos", "MnemosStore", "Memory", " version " 证据：`mnemos/__init__.py`
- **Cemelify**（source_file）：CML CEMELIFY SYSTEM = ⋮---- def cemelify content: str, max tokens: int = 512 - str ⋮---- messages = ⋮---- response = chat messages, max tokens=max tokens, temperature=0.2, timeout=90 ⋮---- cemelified = response.strip ⋮---- def needs cemelify content: Optional str - bool ⋮---- first line = content.strip .split "\n" 0 starts with cml = any 证据：`mnemos/cemelify.py`
- **Cli**（source_file）：def ensure utf8 output ⋮---- enc = getattr stream, "encoding", None or "" .lower .replace "-", "" ⋮---- def cmd add mnemos, args ⋮---- result = mnemos.store memory ⋮---- def cmd search mnemos, args ⋮---- result = mnemos.search ⋮---- mid = r.get "id" project = r.get "project", "" content = r.get "content" or "" :120 ⋮---- v = getattr args, k, None ⋮---- result = mnemos.update args.id, fields ⋮---- def cmd delete mnemos, args ⋮---- result = mnemos.delete args.id, hard=args.hard ⋮---- def cmd stats mnemos, args ⋮---- def cmd tags mnemos, args ⋮---- tags = mnemos.list tags ⋮---- def cmd digest mnemos, args ⋮---- rows = mnemos.digest days=args.days, project=args.project ⋮---- print f" ⋮---- def… 证据：`mnemos/cli.py`
- **Constants**（source_file）：DECAY RATE = 0.015 DECAY RATE SEMANTIC = 0.00385 DECAY FLOOR = 0.1 ⋮---- HYBRID MIN MEMORIES = 10 RRF K = 60 ⋮---- BM25 WEIGHTS = 5.0, 2.0, 3.0 ⋮---- IMPORTANCE THRESHOLDS = 20, 8 , 10, 7 , 5, 6 ⋮---- VEC DEDUP MAX DISTANCE = 0.40 ⋮---- IMPORTANCE BOOST = 0.3 ACCESS BOOST = 0.05 ACCESS CAP = 20 ⋮---- CONFIRM BOOST 30D = 0.3 CONFIRM BOOST 90D = 0.15 ⋮---- CONTRADICTION VEC THRESHOLD = 0.35 CONTRADICTION RERANK MIN = 0.35 CONTRADICTION RERANK HIGH = 0.60 ⋮---- CONTRADICTION RERANK THRESHOLD = CONTRADICTION RERANK MIN ⋮---- DEFAULT CONTRADICT MODE = os.environ.get ⋮---- DEDUP RERANK THRESHOLD = 0.85 ⋮---- NLI EN MODEL = os.environ.get NLI MULTI MODEL = os.environ.get NLI MAX LENGTH = 512 ⋮----… 证据：`mnemos/constants.py`
- **--- Store ---**（source_file）：CML TYPE PREFIXES = "D:", "C:", "F:", "L:", "P:", "W:", "R:" ⋮---- @contextmanager def regex time limit ⋮---- seconds = int os.environ.get "MNEMOS BULK REWRITE TIMEOUT", "30" or 0 ⋮---- seconds = 30 ⋮---- def raise signum, frame ⋮---- old = signal.signal signal.SIGALRM, raise ⋮---- def sigmoid x ⋮---- def summarize quick check rows ⋮---- msgs = r 0 for r in rows or "ok" ⋮---- shown = "; ".join msgs :3 ⋮---- def corruption hint exc ⋮---- """If exc looks like SQLite on-disk corruption, return an actionable hint, else None. Turns a raw 'database disk image is malformed' into guidance.""" msg = str exc .lower ⋮---- def extract cml subject content ⋮---- first line = content.strip .split "\n" 0 ⋮… 证据：`mnemos/core.py`
- **L2-normalize each vector so cosine similarity can be computed as a**（source_file）：instance = None last used = 0.0 lock = threading.Lock ⋮---- def get model ⋮---- kwargs = { ⋮---- instance = TextEmbedding kwargs last used = time.monotonic ⋮---- def maybe unload force=False ⋮---- def embed texts, prefix="passage" ⋮---- texts = texts ⋮---- prefixed = f"{prefix}: {t}" for t in texts ⋮---- model = get model L2-normalize each vector so cosine similarity can be computed as a simple dot product and L2 distance stays bounded in 0, 2 . Recent fastembed versions no longer normalize e5-large output, so we do it here explicitly, all downstream thresholds dedup, contradiction detection assume unit-norm vectors. out = ⋮---- v = list vec norm = math.sqrt sum x x for x in v ⋮---- v = x /… 证据：`mnemos/embed.py`
- **--- Tool definitions ---**（source_file）：STORE DESC CML = ⋮---- STORE DESC PROSE = ⋮---- STORE DESCRIPTION = STORE DESC PROSE if CML MODE == "off" else STORE DESC CML ⋮---- CONTENT DESC CML = "The memory content. Use CML for facts/decisions/configs; use prose for runbooks/docs/code see description ." CONTENT DESC PROSE = "The memory content as clear natural prose." CONTENT DESCRIPTION = CONTENT DESC PROSE if CML MODE == "off" else CONTENT DESC CML ⋮---- LOCK DESC STORE CML = "Set true for prose-format content runbooks, long docs, code blocks to prevent the Nyx cycle from cemelifying it." LOCK DESC STORE PROSE = "Set true to prevent the Nyx cycle from merging this memory with others during consolidation." LOCK DESCRIPTION STORE = L… 证据：`mnemos/mcp_server.py`
- **Tokenize: alphanumeric + Unicode word chars**（source_file）：STOP WORDS = { ⋮---- def clean fts query raw: str, mode: str = "AND" - str ⋮---- Tokenize: alphanumeric + Unicode word chars tokens = re.findall r"\w+", raw.lower , re.UNICODE tokens = t for t in tokens if t not in STOP WORDS and len t = 2 ⋮---- parts = f'"{t}"' for t in tokens ⋮---- def fts dedup store, content: str, top n: int = 5, threshold: float = 0.6 ⋮---- tokens = set t for t in re.findall r"\w+", content.lower , re.UNICODE ⋮---- fts query = clean fts query content, mode="OR" ⋮---- candidate ids = store.search fts fts query, limit=top n 3, and mode=False ⋮---- memories = store.get memories by ids candidate ids :top n 3 results = ⋮---- mem tokens = set ⋮---- overlap = len tokens & mem… 证据：`mnemos/query.py`
- **Rerank**（source_file）：instance = None last used = 0.0 lock = threading.Lock ⋮---- def get reranker ⋮---- kwargs = { ⋮---- instance = TextCrossEncoder kwargs ⋮---- last used = time.monotonic ⋮---- def maybe unload force=False ⋮---- def rerank query: str, documents: list - list ⋮---- model = get reranker texts = d.get "text", "" for d in documents scores = list model.rerank query, texts ⋮---- def rrf merge ranked lists, k=60 ⋮---- scores = {} 证据：`mnemos/rerank.py`
- **Drop only leading/trailing blank separator lines; content lines**（source_file）：SPLIT THRESHOLD = int os.environ.get "MNEMOS SPLIT THRESHOLD", "4000" SPLIT TARGET = int os.environ.get "MNEMOS SPLIT TARGET", "2400" ⋮---- SENT BOUNDARY = re.compile r" ?<= .!?; \s+" ⋮---- def split enabled ⋮---- """Whether auto-splitting is on. Default on; set MNEMOS SPLIT ENABLED=0 to disable.""" ⋮---- def blocks content ⋮---- """Group lines into blocks at blank-line boundaries. Each block is a list of consecutive non-blank lines a paragraph or a CML block such as a heading plus the facts under it . Blank lines are treated purely as separators and are not preserved as content. """ blocks = cur = ⋮---- def split content content, threshold=None, target=None, hard=False ⋮---- """Split conte… 证据：`mnemos/splitter.py`
- **Mnemos Session Hook**（source_file）：set -euo pipefail MNEMOS BIN="${MNEMOS BIN:-mnemos}" STATE DIR="${MNEMOS SESSION STATE DIR:-/tmp/mnemos-session}" mkdir -p "$STATE DIR" 2 /dev/null true case "${1:-start}" in start if -n "${CLAUDE SESSION ID:-}" ; then rm -f "$STATE DIR/${CLAUDE SESSION ID}.primed" 2 /dev/null true fi find "$STATE DIR" -type f -mtime +7 -delete 2 /dev/null true "$MNEMOS BIN" briefing 2 /dev/null true CWD CONTEXT="${CLAUDE PROJECT DIR:-${PWD:-}}" if -n "$CWD CONTEXT" ; then echo "" echo " "$MNEMOS BIN" prime "$CWD CONTEXT" --limit 3 2 /dev/null true fi ;; prompt PAYLOAD=$ cat 2 /dev/null true SID="${CLAUDE SESSION ID:-$ echo "$PAYLOAD" jq -r '.session id // empty' 2 /dev/null }" PROMPT TEXT=$ echo "$PAYLOAD"… 证据：`scripts/mnemos-session-hook.sh`
- **Mechanical**（source_file）：TAU DUP = 0.70 PREFILTER JACCARD = 0.10 ⋮---- WORD = re.compile r" a-za-åäö0-9 ./ ⋮---- ordered = sorted inputs, key=lambda m: m.get "created at" or "" pool = ⋮---- nli calls = prefiltered = 0 ⋮---- dup = None ⋮---- dup = {"partner": k, "score": 1.0} ⋮---- score = min e1, e2 ⋮---- dup = {"partner": k, "score": score} 证据：`benchmarks/merge-bench/mechanical.py`
- **Init**（source_file）：all = "run nyx cycle" 证据：`mnemos/consolidation/__init__.py`
- **Endpoints that rejected the temperature parameter, keyed url, model .**（source_file）：DEFAULT API URL = "https://api.openai.com/v1/chat/completions" DEFAULT MODEL = None DEFAULT FAST MODEL = None ⋮---- LLM TIMEOUT = int os.environ.get "MNEMOS LLM TIMEOUT", "240" ⋮---- LLM WALL BUDGET = int os.environ.get "MNEMOS LLM WALL BUDGET", "480" ⋮---- def get config phase=None ⋮---- phase suffix = f" {phase.upper }" if phase else "" phase model = os.environ.get f"MNEMOS LLM MODEL{phase suffix}" if phase else None phase url = os.environ.get f"MNEMOS LLM API URL{phase suffix}" if phase else None phase key = os.environ.get f"MNEMOS LLM API KEY{phase suffix}" if phase else None phase omit temp = os.environ.get f"MNEMOS LLM OMIT TEMPERATURE{phase suffix}" if phase else None omit temp = pha… 证据：`mnemos/consolidation/llm.py`
- **Mechanical**（source_file）：WORD = re.compile r" a-za-åäö0-9 ./ ⋮---- def lines of content ⋮---- text = explode cml chain content out = ⋮---- ln = ln.strip ⋮---- def words line ⋮---- def prefilter pass la, lb ⋮---- tau = MECH MERGE TAU ⋮---- min line chars = MECH MERGE MIN LINE CHARS ⋮---- members = mem by id mid for mid in cluster ids if mem by id.get mid members = m for m in members if m.get "content" or "" .strip ⋮---- pool = ⋮---- kept = ⋮---- duplicate = False ⋮---- duplicate = True ⋮---- score = nli.bidirectional entailment cand, k 证据：`mnemos/consolidation/mechanical.py`
- **--- Schema migration ---**（source_file）：SOURCE KEY = "memory" ⋮---- def log msg ⋮---- ts = time.strftime "%Y-%m-%d %H:%M:%S" ⋮---- --- Schema migration --- ⋮---- def migrate nyx schema conn ⋮---- """Ensure Nyx-cycle-adjacent schema exists. Mostly a no-op post-v10.2.1: consolidation log and nyx state now live in SQLiteStore.init schema so they exist from first DB connection not just first Nyx run . This function is kept as a safety net for older DBs that predate v10.2.1 and may not have seen a fresh init, plus for the idx links type index which is not redundantly created elsewhere. """ ⋮---- Backfill the v10.5.0 bookkeeping columns on DBs whose consolidation log predates them. SQLite has no ADD COLUMN IF NOT EXISTS, so the swallow… 证据：`mnemos/consolidation/orchestrator.py`
- **=============================================================================**（source_file）：def active namespace ⋮---- def merge prompt ⋮---- def synthesis prompt ⋮---- def fastembed embed texts, prefix="passage" ⋮---- prefix = "query" ⋮---- def vec join col conn ⋮---- def archive memory conn, mid, tag suffix=None ⋮---- def store embeddings conn, tuples, model=None ⋮---- join col = vec join col conn ⋮---- existing = conn.execute ⋮---- cur = conn.execute vec id = cur.lastrowid ⋮---- def log msg ⋮---- ts = time.strftime "%Y-%m-%d %H:%M:%S" ⋮---- ============================================================================= Shared helpers ⋮---- def load embeddings conn, project=None, namespace=None ⋮---- """Load active memory embeddings. Returns all embeddings, mergeable embeddings, m… 证据：`mnemos/consolidation/phases.py`
- **Prompts**（source_file）：MERGE SYSTEM = """You consolidate memories into one CML block. Your job is UNIQUE INFORMATION PRESERVATION with dense formatting. ⋮---- MERGE SYSTEM PROSE = """You consolidate memories into one paragraph of clear English prose. Your job is UNIQUE INFORMATION PRESERVATION with natural writing. ⋮---- WEAVE SYSTEM = """You analyze pairs of memories from different life domains to find genuine cross-domain connections. ⋮---- CONTRADICT SYSTEM = """You compare two memories from the same project and classify their relationship. They may or may not be about the same subject; decide that first. ⋮---- SYNTHESIS SYSTEM = """You are performing "Nyx consolidation" on a person's memory corpus. ⋮---- SYNT… 证据：`mnemos/consolidation/prompts.py`
- **Init**（source_file）：all = "MnemosStore", "Memory", "SearchResult", "SQLiteStore" ⋮---- def get qdrant store args, kwargs ⋮---- def get postgres store args, kwargs 证据：`mnemos/storage/__init__.py`
- **Insert-into-arch and delete-from-active commit together: a crash in**（source_file）：def serialize vec vec ⋮---- def vec join col conn conn, table ⋮---- def arch join col conn ⋮---- join col = arch join col conn existing = conn.execute ⋮---- cur = conn.execute meta id = cur.lastrowid ⋮---- vec id = cur.lastrowid ⋮---- def move embedding to archive conn conn, mid, source key="memory" ⋮---- active col = vec join col conn conn, "embed vec" meta = conn.execute ⋮---- vrow = conn.execute ⋮---- Insert-into-arch and delete-from-active commit together: a crash in between must not leave the vector in both indexes invisible to the reconcile check, which only looks for missing arch copies . ⋮---- def ensure vec db path, dims=FASTEMBED DIMS ⋮---- """Open a SQLite connection with the sql… 证据：`mnemos/storage/sqlite_store.py`
- **Changelog**（documentation）：All notable changes to Mnemos. Dates are from the original private development repository, where the system existed under an internal name agent-memory before being open-sourced as Mnemos in this repo. 证据：`CHANGELOG.md`
- **Mnemos Quickstart**（documentation）：Five-minute walkthrough. For the full story architecture, benchmarks, CML, Nyx cycle, storage backends read README.md README.md after this. 证据：`QUICKSTART.md`
- **Roadmap**（documentation）：Loose, opinionated, subject to change. Not a release schedule. Items move to CHANGELOG.md when shipped. 证据：`ROADMAP.md`
- **Cml Fidelity Corpus**（structured_config）：{ "description": "Hand-curated synthetic prose memories for the CML fidelity benchmark. All entries are fictional; any resemblance to real infrastructure or people is illustrative. Covers two input styles: 1 fact-dense production-memory style cfg- , dec- , con- , pref- , fact- , warn- , learn- , runbook- , short, minimal filler, reads like a structured note. 2 narrative style narr- , longer, rambling, lots of connective tissue, reads like someone dictating what happened. The bench cemelifies each into CML and measures how many of the original atomic facts survive; the two styles together show both ends of the compression range fact-dense condenses 15-25%, narrative 35-60% .", "memories": {… 证据：`benchmarks/cml_fidelity_corpus.json`
- **Cml Fidelity Gpt4O**（structured_config）：{ "corpus": "cml fidelity corpus.json", "n memories": 20, "total facts": 209, "total preserved": 201, "overall preservation rate": 0.9617, "average compression ratio": 0.683, "per memory": { "id": "cfg-01", "category": "config", "prose len": 391, "cml len": 271, "compression ratio": 0.693, "n original facts": 14, "n preserved": 14, "preservation rate": 1.0, "dropped facts": , "cml output": "F: Production Redis on redis-prod-a.internal:6380, TLS enabled; maxmemory=4GB, allkeys-lru eviction; replica=redis-prod-b.internal, async replication, lag = 0.55 indicates duplicates, below is noise. F: Threshold set as DEDUP RERANK THRESHOLD in mnemos.constants." }, { "id": "learn-02", "category": "lear… 证据：`benchmarks/cml_fidelity_gpt4o.json`
- **Cml Fidelity Gpt4O Mini**（structured_config）：{ "corpus": "cml fidelity corpus.json", "n memories": 20, "total facts": 209, "total preserved": 199, "overall preservation rate": 0.9522, "average compression ratio": 0.754, "per memory": { "id": "cfg-01", "category": "config", "prose len": 391, "cml len": 325, "compression ratio": 0.831, "n original facts": 14, "n preserved": 13, "preservation rate": 0.9286, "dropped facts": , "cml output": "F: Production Redis runs on redis-prod-a.internal:6380 with TLS enabled; Maxmemory: 4GB, eviction: allkeys-lru; Replica: redis-prod-b.internal, async replication, lag usually under 50ms; Backups: offsite object store nightly at 03:15 UTC; No disk persistence on primary: RDB disabled, AOF off, write la… 证据：`benchmarks/cml_fidelity_gpt4o_mini.json`
- **Cml Fidelity Haiku**（structured_config）：{ "corpus": "cml fidelity corpus.json", "n memories": 20, "total facts": 209, "total preserved": 205, "overall preservation rate": 0.9809, "average compression ratio": 0.692, "per memory": { "id": "cfg-01", "category": "config", "prose len": 391, "cml len": 234, "compression ratio": 0.598, "n original facts": 14, "n preserved": 13, "preservation rate": 0.9286, "dropped facts": "Disk persistence is intentionally disabled on the primary" , "cml output": "F: redis-prod-a.internal:6380 TLS enabled; maxmemory 4GB allkeys-lru; replica redis-prod-b.internal async replication ~50ms lag; nightly backup 03:15 UTC offsite object store; RDB disabled, AOF off \u2235 p99 write latency cautious hedging; r… 证据：`benchmarks/cml_fidelity_haiku.json`
- **Cml Fidelity Llama70B**（structured_config）：{ "corpus": "cml fidelity corpus.json", "n memories": 20, "total facts": 209, "total preserved": 185, "overall preservation rate": 0.8852, "average compression ratio": 0.788, "per memory": { "id": "cfg-01", "category": "config", "prose len": 391, "cml len": 328, "compression ratio": 0.839, "n original facts": 14, "n preserved": 14, "preservation rate": 1.0, "dropped facts": , "cml output": "F: Production Redis \u2192 redis-prod-a.internal:6380, TLS enabled; maxmemory 4GB, allkeys-lru eviction; replica redis-prod-b.internal, async replication, lag ~50ms; backups offsite object store, nightly 03:15 UTC; D: RDB disabled, AOF off \u2235 write latency = 0.55 correlates with duplicates, below is… 证据：`benchmarks/cml_fidelity_llama70b.json`
- **Cml Fidelity Minimax**（structured_config）：{ "corpus": "cml fidelity corpus.json", "n memories": 19, "total facts": 202, "total preserved": 109, "overall preservation rate": 0.5396, "average compression ratio": 0.643, "per memory": { "id": "cfg-01", "category": "config", "prose len": 391, "cml len": 115, "compression ratio": 0.294, "n original facts": 14, "n preserved": 5, "preservation rate": 0.3571, "dropped facts": "Production Redis replica is redis-prod-b.internal", "Replication between redis-prod-a.internal and redis-prod-b.internal is asynchronous", "Replication lag is usually under 50ms", "Backups are sent to an offsite object store", "Backups run nightly at 03:15 UTC", "RDB persistence is disabled on the primary", "AOF is di… 证据：`benchmarks/cml_fidelity_minimax.json`
- **Cml Fidelity Opus**（structured_config）：{ "corpus": "cml fidelity corpus.json", "n memories": 20, "total facts": 209, "total preserved": 209, "overall preservation rate": 1.0, "average compression ratio": 0.792, "per memory": { "id": "cfg-01", "category": "config", "prose len": 391, "cml len": 345, "compression ratio": 0.882, "n original facts": 14, "n preserved": 14, "preservation rate": 1.0, "dropped facts": , "cml output": "F: Production Redis @ redis-prod-a.internal:6380; TLS enabled; maxmemory=4GB; eviction=allkeys-lru\nF: Replica @ redis-prod-b.internal; async replication; lag typically = 0.55 empirically correlates with \"actually a duplicate\"; below = noise\nF: Threshold set as DEDUP RERANK THRESHOLD in mnemos.constants"… 证据：`benchmarks/cml_fidelity_opus.json`
- **Cml Fidelity Qwen3**（structured_config）：{ "corpus": "cml fidelity corpus.json", "n memories": 9, "total facts": 98, "total preserved": 79, "overall preservation rate": 0.8061, "average compression ratio": 0.566, "per memory": { "id": "dec-01", "category": "decision", "prose len": 440, "cml len": 235, "compression ratio": 0.534, "n original facts": 12, "n preserved": 8, "preservation rate": 0.6667, "dropped facts": "Alternatives considered were pgvector, Chroma, and Weaviate", "pgvector was rejected because it requires a separate server process", "Chroma was rejected because it requires a separate server process", "Weaviate was rejected because it requires a separate server process" , "cml output": "D: sqlite-vec selected over pgv… 证据：`benchmarks/cml_fidelity_qwen3.json`
- **Cml Fidelity Sonnet**（structured_config）：{ "corpus": "cml fidelity corpus.json", "n memories": 20, "total facts": 209, "total preserved": 205, "overall preservation rate": 0.9809, "average compression ratio": 0.714, "per memory": { "id": "cfg-01", "category": "config", "prose len": 391, "cml len": 294, "compression ratio": 0.752, "n original facts": 14, "n preserved": 14, "preservation rate": 1.0, "dropped facts": , "cml output": "F: Redis prod @ redis-prod-a.internal:6380; TLS enabled; maxmemory=4GB; eviction=allkeys-lru\nF: replica=redis-prod-b.internal; async replication; lag~ cautious hedging\nP: honest opinions on review requests \u2717 validation\nP: suggested text blocks \u2192 copyable code fences\nF: writing projects \u27… 证据：`benchmarks/cml_fidelity_sonnet.json`
- **Locomo10**（structured_config）：{ "qa": { "question": "When did Caroline go to the LGBTQ support group?", "answer": "7 May 2023", "evidence": "D1:3" , "category": 2 }, { "question": "When did Melanie paint a sunrise?", "answer": 2022, "evidence": "D1:12" , "category": 2 }, { "question": "What fields would Caroline be likely to pursue in her educaton?", "answer": "Psychology, counseling certification", "evidence": "D1:9", "D1:11" , "category": 3 }, { "question": "What did Caroline research?", "answer": "Adoption agencies", "evidence": "D2:8" , "category": 1 }, { "question": "What is Caroline's identity?", "answer": "Transgender woman", "evidence": "D1:5" , "category": 1 }, { "question": "When did Melanie run a charity race… 证据：`benchmarks/locomo10.json`
- **Qa Results Hybrid+Rerank K5 Sonnet Opus**（structured_config）：{ "mode": "hybrid+rerank", "k": 5, "answerer": "sonnet", "judge": "opus", "overall accuracy": 0.0, "evaluated": 3, "total": 3, "per type": { "single-session-user": { "accuracy": 0.0, "n": 3 } }, "answerer fails": 0, "judge fails": 0, "per question": { "qid": "e47becba", "type": "single-session-user", "correct": false, "system answer": "I don't have enough information to answer that.", "reference": "Business Administration", "retrieved": "answer 280352e9", "d414cac5 4", "f6859b48 2", "sharegpt UnjngE7 65", "aae4411b 2" }, { "qid": "118b2229", "type": "single-session-user", "correct": false, "system answer": "I don't have enough information to answer that.", "reference": "45 minutes each way"… 证据：`benchmarks/qa_results_hybrid+rerank_k5_sonnet_opus.json`
- **Qa Results Hybrid K5 Gpt4O Gpt4O Cml**（structured_config）：{ "mode": "hybrid", "k": 5, "answerer": "gpt4o", "judge": "gpt4o", "cml context": true, "overall accuracy": 0.586, "evaluated": 500, "total": 500, "per type": { "single-session-user": { "accuracy": 0.84375, "n": 64 }, "abstention": { "accuracy": 1.0, "n": 30 }, "multi-session": { "accuracy": 0.47107438016528924, "n": 121 }, "single-session-preference": { "accuracy": 0.16666666666666666, "n": 30 }, "temporal-reasoning": { "accuracy": 0.5196850393700787, "n": 127 }, "knowledge-update": { "accuracy": 0.8055555555555556, "n": 72 }, "single-session-assistant": { "accuracy": 0.4107142857142857, "n": 56 } }, "answerer fails": 0, "judge fails": 0, "per question": { "qid": "e47becba", "type": "singl… 证据：`benchmarks/qa_results_hybrid_k5_gpt4o_gpt4o_cml.json`
- **Qa Results Hybrid K5 Sonnet Opus**（structured_config）：{ "mode": "hybrid", "k": 5, "answerer": "sonnet", "judge": "opus", "overall accuracy": 0.774, "evaluated": 500, "total": 500, "per type": { "single-session-user": { "accuracy": 0.9375, "n": 64 }, "abstention": { "accuracy": 0.9666666666666667, "n": 30 }, "multi-session": { "accuracy": 0.6611570247933884, "n": 121 }, "single-session-preference": { "accuracy": 0.4666666666666667, "n": 30 }, "temporal-reasoning": { "accuracy": 0.7244094488188977, "n": 127 }, "knowledge-update": { "accuracy": 0.8194444444444444, "n": 72 }, "single-session-assistant": { "accuracy": 0.9464285714285714, "n": 56 } }, "answerer fails": 0, "judge fails": 0, "per question": { "qid": "e47becba", "type": "single-session… 证据：`benchmarks/qa_results_hybrid_k5_sonnet_opus.json`
- **Results Hybrid+Rerank Session**（structured_config）：{ "mode": "hybrid+rerank", "granularity": "session", "recall": { "1": 0.9425531914893617, "3": 0.9808510638297873, "5": 0.9893617021276596, "10": 0.9914893617021276 }, "ndcg": { "5": 0.9721628238546629, "10": 0.9702022913354329 }, "per type": { "single-session-user": { "1": 0.984375, "3": 1.0, "5": 1.0, "10": 1.0 }, "multi-session": { "1": 0.9834710743801653, "3": 1.0, "5": 1.0, "10": 1.0 }, "single-session-preference": { "1": 0.7333333333333333, "3": 0.8666666666666667, "5": 1.0, "10": 1.0 }, "temporal-reasoning": { "1": 0.9133858267716536, "3": 0.9763779527559056, "5": 0.9763779527559056, "10": 0.9763779527559056 }, "knowledge-update": { "1": 0.9861111111111112, "3": 1.0, "5": 1.0, "10":… 证据：`benchmarks/results_hybrid+rerank_session.json`
- **Results Hybrid+Rerank Session Cml**（structured_config）：{ "mode": "hybrid+rerank", "cml conversion": true, "granularity": "session", "completed at": "2026-04-11T00:59:33+02:00", "notes": "Canonical Mnemos: CML normalization + hybrid retrieval + Jina v2 cross-encoder reranker. This is the configuration the system was designed to run in and the one I use in production. CML conversion is applied once at storage time using Claude Haiku 4.5 via DO Gradient API cached on disk by SHA256, so re-runs are free ; after that, the search path is identical to the no-CML hybrid+rerank benchmark and contains zero LLM calls of any kind. The reranker is a discriminative scorer, not a generative language model. First run, no parameter tuning, no thresholds swept,… 证据：`benchmarks/results_hybrid+rerank_session_cml.json`
- **Results Hybrid Session**（structured_config）：{ "mode": "hybrid", "granularity": "session", "completed at": "2026-04-10T06:02:37+02:00", "notes": "Lightweight mode: FTS5 + sqlite-vec + RRF. No reranker, no CML preprocessing. The lightest configuration Mnemos ships, intended for sub-1 GB / Pi-class deployments. First run, no parameter tuning.", "recall": { "1": 0.9191489361702128, "3": 0.9702127659574468, "5": 0.9808510638297873, "10": 0.9893617021276596 }, "ndcg": { "5": 0.9604562126411953, "10": 0.959948903860709 }, "per type": { "single-session-user": { "1": 0.984375, "3": 1.0, "5": 1.0, "10": 1.0 }, "multi-session": { "1": 0.9421487603305785, "3": 0.9917355371900827, "5": 1.0, "10": 1.0 }, "single-session-preference": { "1": 0.6, "3… 证据：`benchmarks/results_hybrid_session.json`
- **Results Hybrid Session Cml**（structured_config）：{ "mode": "hybrid", "cml conversion": true, "granularity": "session", "completed at": "2026-04-11T00:59:30+02:00", "notes": "Hybrid retrieval with CML normalization of stored memories, no reranker. CML is applied at storage time using Claude Haiku 4.5 via DO Gradient API cached on disk by SHA256 , then the same FTS5 + sqlite-vec + RRF pipeline as the no-CML lite mode runs. The bi-encoder is mildly out of distribution on CML's structural form e5-large was trained on natural-language pairs , which is why this lite-mode-with-CML number sits slightly below the no-CML lite mode. The reranker more than rescues this gap in the canonical configuration.", "recall": { "1": 0.925531914893617, "3": 0.9… 证据：`benchmarks/results_hybrid_session_cml.json`
- **Results Locomo Hybrid+Rerank Cml**（structured_config）：{ "benchmark": "LoCoMo", "dataset path": "/root/work/mnemos/benchmarks/locomo10.json", "mode": "hybrid+rerank", "cml": true, "max k": 10, "questions evaluated": 1536, "adversarial skipped": 446, "failures": 4, "recall any": { "1": 0.609375, "3": 0.796875, "5": 0.8606770833333334, "10": 0.9192708333333334 }, "recall all": { "1": 0.4811197916666667, "3": 0.6783854166666666, "5": 0.75, "10": 0.82421875 }, "ndcg": { "1": 0.609375, "3": 0.7735678294898642, "5": 0.7969905525067854, "10": 0.8049884681952891 }, "per category": { "2": { "label": "multi-hop", "n": 321, "recall any@1": 0.6853582554517134, "recall any@3": 0.8286604361370716, "recall any@5": 0.881619937694704, "recall any@10": 0.9345794… 证据：`benchmarks/results_locomo_hybrid+rerank_cml.json`
- **Results Locomo Hybrid**（structured_config）：{ "benchmark": "LoCoMo", "dataset path": "/root/work/mnemos/benchmarks/locomo10.json", "mode": "hybrid", "cml": false, "max k": 10, "questions evaluated": 1536, "adversarial skipped": 446, "failures": 4, "recall any": { "1": 0.5787760416666666, "3": 0.7701822916666666, "5": 0.8470052083333334, "10": 0.9401041666666666 }, "recall all": { "1": 0.4654947916666667, "3": 0.6432291666666666, "5": 0.72265625, "10": 0.8548177083333334 }, "ndcg": { "1": 0.5787760416666666, "3": 0.7431507794770761, "5": 0.7710436056208311, "10": 0.7890637080130191 }, "per category": { "2": { "label": "multi-hop", "n": 321, "recall any@1": 0.6074766355140186, "recall any@3": 0.7538940809968847, "recall any@5": 0.81619… 证据：`benchmarks/results_locomo_hybrid.json`
- **Results Locomo Hybrid Cml**（structured_config）：{ "benchmark": "LoCoMo", "dataset path": "/root/work/mnemos/benchmarks/locomo10.json", "mode": "hybrid", "cml": true, "max k": 10, "questions evaluated": 1536, "adversarial skipped": 446, "failures": 4, "recall any": { "1": 0.4895833333333333, "3": 0.69921875, "5": 0.7936197916666666, "10": 0.91015625 }, "recall all": { "1": 0.3899739583333333, "3": 0.5709635416666666, "5": 0.669921875, "10": 0.8040364583333334 }, "ndcg": { "1": 0.4895833333333333, "3": 0.6652191146682039, "5": 0.7013614193991113, "10": 0.729770615178506 }, "per category": { "2": { "label": "multi-hop", "n": 321, "recall any@1": 0.5295950155763239, "recall any@3": 0.7133956386292835, "recall any@5": 0.8130841121495327, "rec… 证据：`benchmarks/results_locomo_hybrid_cml.json`
- **Database files contain personal data**（source_file）：Database files contain personal data .db .db-journal .db-wal .db-shm 证据：`.gitignore`
- **Mnemos Logo Dark**（source_file）： 证据：`assets/mnemos-logo-dark.svg`
- 其余 16 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。

## 宿主 AI 必须遵守的规则

- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`README.md`, `benchmarks/README.md`, `docs/ARCHITECTURE.md`
- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`README.md`, `benchmarks/README.md`, `docs/ARCHITECTURE.md`

## 用户开工前应该回答的问题

- 你准备在哪个宿主 AI 或本地环境中使用它？
- 你只是想先体验工作流，还是准备真实安装？
- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？

## 验收标准

- 所有能力声明都能回指到 evidence_refs 中的文件路径。
- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。
- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。

---

## Doramagic Context Augmentation

下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。

## Human Manual 骨架

使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。

宿主 AI 硬性规则：
- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。
- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。
- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。

- **系统总览与架构**：importance `high`
  - source_paths: README.md, mnemos/__init__.py, mnemos/mcp_server.py, mnemos/cli.py, mnemos/constants.py
- **检索流水线与存储后端**：importance `high`
  - source_paths: mnemos/core.py, mnemos/query.py, mnemos/embed.py, mnemos/rerank.py, mnemos/cemelify.py
- **Nyx 整合循环与 NLI 决策层**：importance `high`
  - source_paths: mnemos/consolidation/__init__.py, mnemos/consolidation/orchestrator.py, mnemos/consolidation/mechanical.py, mnemos/consolidation/llm.py, mnemos/consolidation/phases.py
- **运维、自检与故障排查**：importance `high`
  - source_paths: mnemos/cli.py, mnemos/mcp_server.py, mnemos/core.py, mnemos/storage/sqlite_store.py, mnemos/constants.py

## Repo Inspection Evidence / 源码检查证据

- repo_clone_verified: true
- repo_inspection_verified: true
- repo_commit: `b0db82a4c6b239641dfe64bc7005f64da6058f6d`
- inspected_files: `README.md`, `pyproject.toml`, `docs/ARCHITECTURE.md`, `docs/agent-instructions.md`, `docs/benchmarks.md`, `docs/cml.md`, `docs/comparison.md`, `docs/english-primary.md`, `docs/features.md`, `docs/origin.md`, `docs/philosophy.md`, `docs/plans/2026-07-03-zero-llm-daily-cycle.md`, `docs/session-hooks.md`, `docs/usage.md`

宿主 AI 硬性规则：
- 没有 repo_clone_verified=true 时，不得声称已经读过源码。
- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。
- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。

## Doramagic Pitfall Constraints / 踩坑约束

这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。

### Constraint 1: 失败模式：installation: v10.15.0 NLI decision layer: entailment-based dedup confirm, contradiction detection, Nyx pha...

- Trigger: Developers should check this installation risk before relying on the project: v10.15.0 NLI decision layer: entailment-based dedup confirm, contradiction detection, Nyx phase-4 finder
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: v10.15.0 NLI decision layer: entailment-based dedup confirm, contradiction detection, Nyx phase-4 finder. Context: Observed during installation or first-run setup.
- Why it matters: Upgrade or migration may change expected behavior: v10.15.0 NLI decision layer: entailment-based dedup confirm, contradiction detection, Nyx phase-4 finder
- Evidence: failure_mode_cluster:github_release | https://github.com/draca-glitch/Mnemos/releases/tag/v10.15.0 | v10.15.0 NLI decision layer: entailment-based dedup confirm, contradiction detection, Nyx phase-4 finder
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 2: 失败模式：installation: v10.16.0 ONNX backend for the NLI layer; self-healing temperature rejection

- Trigger: Developers should check this installation risk before relying on the project: v10.16.0 ONNX backend for the NLI layer; self-healing temperature rejection
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: v10.16.0 ONNX backend for the NLI layer; self-healing temperature rejection. Context: Source discussion did not expose a precise runtime context.
- Why it matters: Upgrade or migration may change expected behavior: v10.16.0 ONNX backend for the NLI layer; self-healing temperature rejection
- Evidence: failure_mode_cluster:github_release | https://github.com/draca-glitch/Mnemos/releases/tag/v10.16.0 | v10.16.0 ONNX backend for the NLI layer; self-healing temperature rejection
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 3: 失败模式：installation: v10.23.0 doctor flags an empty store instead of blessing it

- Trigger: Developers should check this installation risk before relying on the project: v10.23.0 doctor flags an empty store instead of blessing it
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: v10.23.0 doctor flags an empty store instead of blessing it. Context: Observed during installation or first-run setup.
- Why it matters: Upgrade or migration may change expected behavior: v10.23.0 doctor flags an empty store instead of blessing it
- Evidence: failure_mode_cluster:github_release | https://github.com/draca-glitch/Mnemos/releases/tag/v10.23.0 | v10.23.0 doctor flags an empty store instead of blessing it
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 4: 可能修改宿主 AI 配置

- Trigger: 项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- Host AI rule: 列出会写入的配置文件、目录和卸载/回滚步骤。
- Why it matters: 安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- Evidence: capability.host_targets | https://github.com/draca-glitch/Mnemos | host_targets=mcp_host, claude_code, claude, cursor, chatgpt
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 5: 失败模式：configuration: v10.20.0 phase 0.5 removed; Nyx is namespace-scoped

- Trigger: Developers should check this configuration risk before relying on the project: v10.20.0 phase 0.5 removed; Nyx is namespace-scoped
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: v10.20.0 phase 0.5 removed; Nyx is namespace-scoped. Context: Source discussion did not expose a precise runtime context.
- Why it matters: Upgrade or migration may change expected behavior: v10.20.0 phase 0.5 removed; Nyx is namespace-scoped
- Evidence: failure_mode_cluster:github_release | https://github.com/draca-glitch/Mnemos/releases/tag/v10.20.0 | v10.20.0 phase 0.5 removed; Nyx is namespace-scoped
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 6: 能力判断依赖假设

- Trigger: README/documentation is current enough for a first validation pass.
- Host AI rule: 将假设转成下游验证清单。
- Why it matters: 假设不成立时，用户拿不到承诺的能力。
- Evidence: capability.assumptions | https://github.com/draca-glitch/Mnemos | README/documentation is current enough for a first validation pass.
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 7: 失败模式：migration: v10.24.0 archive-side embedding lifecycle: no more tier-2 leaks

- Trigger: Developers should check this migration risk before relying on the project: v10.24.0 archive-side embedding lifecycle: no more tier-2 leaks
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: v10.24.0 archive-side embedding lifecycle: no more tier-2 leaks. Context: Observed during version upgrade or migration.
- Why it matters: Upgrade or migration may change expected behavior: v10.24.0 archive-side embedding lifecycle: no more tier-2 leaks
- Evidence: failure_mode_cluster:github_release | https://github.com/draca-glitch/Mnemos/releases/tag/v10.24.0 | v10.24.0 archive-side embedding lifecycle: no more tier-2 leaks
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 8: 维护活跃度未知

- Trigger: 未记录 last_activity_observed。
- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。
- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- Evidence: evidence.maintainer_signals | https://github.com/draca-glitch/Mnemos | last_activity_observed missing
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

- Trigger: no_demo
- Evidence: downstream_validation.risk_items | https://github.com/draca-glitch/Mnemos | no_demo; severity=medium
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 10: 存在评分风险

- Trigger: no_demo
- Why it matters: 风险会影响是否适合普通用户安装。
- Evidence: risks.scoring_risks | https://github.com/draca-glitch/Mnemos | no_demo; severity=medium
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。