# Mnemos

> Closed-loop knowledge system for AI agents. Not a Second Brain—it makes knowledge act. KIA loop: load experience before tasks, guard during execution, retrospective after. Persona radar adapts AI to you. Five Guard layers + AI self-checks. Heat L0-L9 auto-retires stale knowledge. Pure Markdown. Local-first. MCP-native.

- **Type:** MCP server
- **Install:** `agentstack add mcp-jielumaizui-mnemos`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [jielumaizui](https://agentstack.voostack.com/s/jielumaizui)
- **Installs:** 0
- **Category:** [Productivity](https://agentstack.voostack.com/c/productivity)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [jielumaizui](https://github.com/jielumaizui)
- **Source:** https://github.com/jielumaizui/Mnemos
- **Website:** https://github.com/jielumaizui/mnemos

## Install

```sh
agentstack add mcp-jielumaizui-mnemos
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Mnemos

**Local Decision Brain & Behavior-Driven System**

> Mnemos v2 beta：本地 AI Agent 知识采集、蒸馏、搜索与行动辅助系统。
>
> 当前 L1 采集、Wiki 蒸馏、KG 补建、PreFlight/Guard 已可用；
> KG 实时事件、评分闭环、主动推送和新鲜度检测仍在完善中。
>
> 🌍 [English Version](README-en.md)

[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/jielumaizui/mnemos/actions)

---

**你是否也被这些问题困扰？**

- 和 AI 聊完一个复杂项目，两周后再问，它已经完全忘了之前的上下文
- 每次遇到同样的问题，都要重新搜索、重新踩一遍同样的坑
- 花了很多时间记笔记、整理文档，但真正需要的时候永远找不到
- 学了很多东西，过了一段时间就忘得一干二净
- 知道自己有很多知识盲区，但不知道盲区在哪里

**所有这些问题，本质上都是同一个问题：人类的认知能力是有限的。**

Mnemos 是一套面向本地运行的 AI Agent 知识系统。它连接你所有的 AI 助手，记录对话，自动提取结构化知识，构建知识图谱，并在你需要的时候推送相关知识。

**当前阶段为 beta，核心链路已可用，但部分高级能力仍在完善中。** 你需要正常和 AI 聊天、正常工作，系统会自动采集和蒸馏。部分功能（如自适应评分、主动推送）需要积累足够数据后才能 fully enable。

灵感源自 [Karpathy 的 LLM Wiki 模式](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)——让 LLM 增量构建并维护持久化的知识库。Mnemos 在此基础上增加了决策辅助层：**知识不是存完就完了，它应该在决策中活着。**

## 它和别的"Second Brain"有什么不同？

| 维度 | 常见 Second Brain 工具 | Mnemos |
|------|----------------------|--------|
| 系统定位 | 知识存储与检索 | Local Decision Brain & Behavior-Driven System |
| 自动化程度 | 半自动（需手动整理/打标签） | beta：自动采集→蒸馏→入库；评分/推送/新鲜度持续完善中 |
| 知识流向 | 你 → 系统 → 你自己查 | 系统 → AI Agent → 实时辅助决策 |
| 质量保障 | 去重（如果有） | 七层蒸馏流水线 + 自适应评分 + 三道自检 |
| 适应能力 | 规则固定 | 冷启动规则 → 贝叶斯自适应 → 行为反馈闭环 |
| 用户建模 | 无 | 三层画像雷达（能量/认知/价值），驱动决策策略 |
| 知识生命周期 | 手动管理或不管 | 评分驱动自动进化，过时知识主动预警，强制复盘闭环 |
| 模块耦合 | 一体化 | 热插拔设计，按需启用 |

## 核心竞争优势

### 存储是底线，不是卖点

知识存储和记忆检索是 Mnemos 最基础的功能。用户可以指定文件经蒸馏后进入知识库，AI 对话记录也会被自动采集并蒸馏为结构化知识——无需手动整理。当前 beta 版本核心链路已可用，高级决策辅助能力仍在持续完善中。

### 一、自适应动态调整引擎

系统内置自适应评分框架（beta），数据积累后逐步从规则驱动过渡到数据驱动：

- **三阶段冷启动**：COLD（纯规则）→ WARM（规则+贝叶斯混合）→ HOT（数据驱动），任何自适应模块在数据不足时都有规则兜底，不会因为"没数据"就罢工
- **贝叶斯评分**：每条知识、每个实体、每段关系都有置信度评分，新证据到来时实时更新后验概率
- **反馈闭环**：隐式信号（搜索/复制/停留时长）+ 显式反馈 → 加权融合 → 驱动评分模型重训练
- **漂移检测**：当特征分布偏移超过 3-sigma 时自动触发模型校准

评分引擎覆盖 6 个子系统：Memos 质量、同步优先级、蒸馏决策、知识图谱置信度、画像稳定性、运维健康度。每个子系统独立评分、独立进化、独立降级。

### 二、用户画像决策中枢

画像不是标签墙，而是决策中枢。系统从 AI 对话行为中推断用户的认知模式和价值取向，并将画像注入 AI 的工作流中：

- **三层雷达**：能量模式（专注/启动/续航/切换）、认知模式（抽象/系统/质疑/创造）、价值优先级（正确/效率/深度/完美/创新/自主）
- **画像驱动对话策略**：根据画像动态生成 AI 提示词片段，让 AI 的行为风格适配用户——完美主义者看到更严谨的建议，效率优先者看到更简洁的方案
- **双画像交叉验证**：行为画像 vs 知识画像，检测"言行不一"——嘴上说注重效率，行为上却在反复优化细节
- **情境隔离**：工作/个人/学习三种情境下的画像独立演进，避免跨界污染
- **14 维演化时间线**：长期追踪画像变化趋势，自动检测倦怠信号、认知转变和价值翻转

### 三、强制复盘与逻辑自检

知识入库不是终点，持续验证才是。系统全自动追踪知识生命周期，在关键时刻强制介入：

- **组合权重强制打开**：系统实时评估每条复盘待办的紧迫性——综合重要性（severity）、等待时长、同类问题频率、当前工作上下文关联度、承诺违约五个维度打分，达到阈值（≥4分）时自动打开 Obsidian 展示决策页面或复盘页面，确保你不会错过关键信号；未达阈值则仅对话内轻提醒，不打断工作流
- **用户预约直接弹开**：用户说"1天后提醒我复盘"，到点直接打开 Obsidian 对应的复盘页面，不走权重算法——你自己约的，系统不废话
- **启动补偿**：关机或合盖期间过期的预约，下次启动时自动补发——过期用户预约立即打开 Obsidian，过期系统提醒走权重判断
- **周报追达升级**：周报生成后 3 天内轻提醒，3 天后仍未读则强制插入对话，7 天后自动归档。配合 Wiki 看板徽章，100% 兜底
- **七层蒸馏流水线**：噪音过滤 → 价值预判 → LLM 判断 → 知识提取 → 自检验证 → 跨 Agent 关联 → 反馈循环。每一层都是一道过滤器，只有通过全部七层的知识才进入知识库
- **可证伪性标记**：每条知识标注可证伪条件和验证状态，过时知识不再沉默——系统会主动提醒"这条知识可能已过时"
- **争议仲裁**：当新知识与已有知识冲突时，不覆盖、不忽略，而是生成仲裁页面记录争议，等用户裁决
- **增量蒸馏 + 延迟蒸馏**：长对话每 5 轮增量生成草稿，低置信度内容进入延迟队列等信号充分后再处理
- **再循环守卫**：防止 Wiki 注入的内容被再次蒸馏回知识库，杜绝知识自引用污染

### 四、热插拔功能模块

Mnemos 的 14+ 子系统是可独立启停的功能模块，不是紧耦合的巨石。全自动运行，模块级故障自动隔离：

- **模块化架构**：每个子系统（知识图谱、影子页面、DNA 指纹、熵引擎、时间胶囊……）独立运行，关掉任何一个不影响核心链路
- **KIA 调度器**：16 步调度任务拓扑排序并行执行，单模块连续 3 次失败自动禁用，不拖垮全局
- **事件驱动**：模块间通过 EventBus 松耦合通信，蒸馏完成→图谱更新→画像刷新→推送评估，全链路异步
- **按需启用**：核心链路（同步→评分→蒸馏）开箱即用，高级功能（向量索引、预测推送、争议仲裁）按需开启

## 架构概览

```
┌─────────────────────────────────────────────────────────────────┐
│  应用层 — 决策输出                                               │
│  IntentRouter │ ApplicationHub │ ContextAwareSearch              │
│  PredictivePush │ BlindspotDiscovery │ DisputeResolver           │
│  FreshnessAlert │ WeeklyReport │ ForcedRetrospective              │
├─────────────────────────────────────────────────────────────────┤
│  知识层 — 理解与建模                                             │
│  ┌──────────────────────┐  ┌──────────────────────────────────┐  │
│  │ 知识图谱              │  │ 用户画像                          │  │
│  │ EntityManager         │  │ 三层雷达 + 交叉验证               │  │
│  │ RelationManager       │  │ 对话策略 + 情境隔离               │  │
│  │ EvolutionTracker      │  │ 14维演化时间线                    │  │
│  │ ContextAwareQuery     │  │ 盲区检测 + 校准                   │  │
│  └──────────────────────┘  └──────────────────────────────────┘  │
├─────────────────────────────────────────────────────────────────┤
│  评分与蒸馏层 — 质量保障                                         │
│  ┌──────────────────────┐  ┌──────────────────────────────────┐  │
│  │ 自适应评分引擎        │  │ 七层蒸馏流水线                    │  │
│  │ COLD/WARM/HOT 三阶段  │  │ 噪音→预判→LLM→提取→自检→关联→反馈│  │
│  │ 6 子系统评分器         │  │ PromptBuilder + TokenBudget       │  │
│  │ 反馈闭环 + 漂移检测    │  │ 增量蒸馏 + 延迟蒸馏               │  │
│  └──────────────────────┘  └──────────────────────────────────┘  │
├─────────────────────────────────────────────────────────────────┤
│  同步层 — 数据摄入                                               │
│  SyncEngine (8步流水线) │ 5 Agent Source │ FileIngestor          │
│  TriggerSystem (Watchdog/Polling/Hybrid) │ AgentLifecycleManager │
└─────────────────────────────────────────────────────────────────┘
```

## 同源复用设计

Mnemos 本身**不直接调用任何 LLM API**。所有需要 LLM 的能力（如知识蒸馏、文档解析）都通过 **AgentDelegate** 委托给用户的本地 AI Agent 处理。

**设计原则：谁启动 Mnemos，蒸馏任务就委托给谁。**

Mnemos 支持 5 个宿主 Agent，通过统一的 `AgentAdapter` 接口接入：

| 适配器 | Agent | 机制 | 状态 |
|--------|-------|------|------|
| Apollon | Claude Code | Hooks (settings.json) | 完整支持 |
| Caduceus | Hermes | Poll + Inbox | 完整支持 |
| Typhon | OpenClaw | SQLite + Hooks | 完整支持 |
| Musae | OpenCode | JSON Config + Hooks | 完整支持 |
| Daedalus | Codex | File-based + Windows .bat | 完整支持 |

无 Agent 宿主时，Mnemos 自动扫描本地安装的 Agent，按优先级选择一个可用的执行蒸馏。

这个设计避免了：
1. **重复配置 API Key**：用户的 Agent 已经配置了 API Key，Mnemos 不需要再要一份
2. **模型版本不一致**：蒸馏用的模型和用户交互的模型保持一致
3. **供应商锁定**：支持任何遵循文件委托协议的 Agent

## 5 分钟快速上手

> 跟着这个例子走一遍，你就知道 Mnemos 在做什么。

### 场景：你让 Claude 解决了一个 bug

**第 1 步：正常对话**

你问 Claude："asyncio.gather 为什么内存爆炸？" 经过一番排查，找到了根因。对话结束。

**第 2 步：全自动蒸馏**

Session End Hook 自动触发蒸馏。对话内容全自动经过七层流水线处理——噪音过滤掉闲聊，价值预判识别出"这是有价值的排障经验"，LLM 提取为结构化知识，自检验证断言和代码片段，最终生成一条知识卡片。

**第 3 步：全自动评分入库**

自适应评分引擎对这条知识自动打分：质量评分 0.85，蒸馏评分 0.92。评分通过，知识卡片自动进入知识库。知识图谱同步创建实体和关系。

**第 4 步：全自动画像学习**

系统从这次对话中自动采集信号：你在排查时表现出高专注深度和质疑倾向，画像参数自动微调。下次类似场景，AI 会提前注入更严谨的排查建议。

**第 5 步：全自动主动决策**

一周后你开始写高并发爬虫。IntentRouter 自动识别任务意图，ContextAwareSearch 检索到之前的排障经验，画像决策中枢判断你应该会关心内存问题——主动在对话开头提醒你注意 asyncio.gather 的坑。

**全程你只需正常对话，系统自动完成后续步骤。** beta 阶段核心链路（采集→蒸馏→入库）已可用，部分高级能力（自适应评分优化、主动推送精准度）仍在持续完善中。

### 验证系统在工作

```bash
# 1. 检查蒸馏队列
python3 core/kia/amphora.py --list

# 2. 检查 daemon 状态
python3 -m mnemos_daemon status

# 3. 查看 Inbox 是否有新内容
ls ~/Documents/Obsidian\ Vault/wiki/00-Inbox/

# 4. 查看画像
cat ~/Documents/Obsidian\ Vault/wiki/01-People/user-persona.md

# 5. 查看评分器状态
python3 mnemos_cli.py scorer status
```

## 🚀 30 秒快速开始

> 跟着走一遍，你就知道 Mnemos 在做什么。

### 前置条件

- Python >= 3.10
- 一个 AI Agent（Claude Code、Hermes、OpenClaw、OpenCode、Codex 等）
- （可选）[Memos](https://github.com/usememos/memos) 实例
- （可选）[Obsidian](https://obsidian.md) 知识库可视化

> **注意**：Mnemos 不直接调用任何 LLM API，所有蒸馏任务都委托给你的 AI Agent 处理。没有 AI Agent，核心功能无法运行。

### 一键安装（推荐）

```bash
git clone https://github.com/jielumaizui/mnemos.git
cd mnemos
./setup.sh        # macOS / Linux
setup.bat         # Windows
```

`setup.sh` 会自动完成：
1. 检查 Python >= 3.10
2. 安装依赖
3. 自动检测 Memos 服务器（如有）
4. 自动检测 Obsidian Vault（如有）
5. 生成 `~/.mnemos/configs/main.json`
6. 初始化标准 wiki 目录结构
7. 安装 AI Agent hooks
8. 启动后台守护进程
9. 配置系统定时任务

全自动模式（无交互）：
```bash
./setup.sh --yes
```

跳过 Memos/Obsidian 检测：
```bash
./setup.sh --skip-memos --skip-obsidian
```

### 手动安装

如果你偏好手动配置：

```bash
# 1. 克隆并安装
git clone https://github.com/jielumaizui/mnemos.git
cd mnemos
pip install -e ".[dev]"

# 2. 复制并编辑配置
mkdir -p ~/.mnemos/configs
cp config/config.example.json ~/.mnemos/configs/main.json
# 编辑 ~/.mnemos/configs/main.json，设置你的 wiki 路径

# 3. 系统诊断
python3 mnemos_cli.py doctor
```

`mnemos doctor` 会自动检测系统状态，检查依赖是否就绪。

### 命令行工具

```bash
mnemos init                       # 交互式配置向导
mnemos doctor                     # 系统诊断
mnemos status                     # 查看系统状态
mnemos config                     # 查看/编辑配置

# Agent 管理
mnemos agent list                 # 列出本地可用的 AI Agent
mnemos agent install              # 为所有可用 Agent 安装 hooks
mnemos agent detect               # 检测已安装的 Agent
mnemos agent doctor               # 诊断 Agent 状态

# 后台服务
mnemos daemon start               # 启动后台守护进程
mnemos daemon stop                # 停止后台守护进程
mnemos daemon status              # 查看守护进程状态
mnemos scheduler install-windows  # 注册 Windows 开机启动
mnemos scheduler uninstall-windows # 卸载 Windows 开机启动

# 事件系统
mnemos events stats               # 查看事件队列统计
mnemos events cleanup             # 清理过期事件

# 评分系统
mnemos scorer status              # 查看评分器状态和模式
mnemos scorer retrain             # 手动触发重训练
mnemos scorer rollback            # 回滚到上一版本模型

# 同步系统
mnemos sync status                # 查看同步状态
mnemos sync retry-failed          # 重试失败的同步任务

# 搜索与报告
mnemos search              # 上下文感知搜索
mnemos report generate            # 生成每周画像报告

# 其他
mnemos calibrate                  # 启动画像校准流程
mnemos mcp serve                  # 启动 MCP 服务器
```

## 与 AI Agent 集成

### 方式一：MCP 协议（推荐，通用）

任何支持 MCP 的 AI Agent 都可以接入。接入后，Agent 可以使用以下工具：

**知识库操作**

| 工具 | 用途 |
|------|------|
| `wiki_search` | 搜索知识库（多来源：文件导入、人工输入、Memos、蒸馏、复盘、Git） |
| `wiki_read` | 读取指定页面（经语义索引、评分、标签处理） |
| `wiki_write` | Agent 写入 Wiki 页面（蒸馏结果、生成的新知识） |
| `wiki_build` | 触发 Wiki 构建（扫描 → 蒸馏 → 生成页面 → 索引更新） |
| `knowledge_source_list` | 查看知识库来源分布统计 |

**知识摄入**

| 工具 | 用途 |
|------|------|
| `knowledge_ingest` | 用户主动口述知识 — 当用户说"记住这个"时调用 |
| `knowledge_import` | 用户指定文件导入 — 解析后写入 Wiki |
| `knowledge_distill` | 通过 LLM API 触发知识蒸馏 — 聊天记录转为结构化 Wiki 知识 |
| `document_process` | 解析文档 — 默认只解析；`write_to_wiki=true` 时 API 蒸馏写入 Wiki |

**会话捕获（推荐）**

| 工具 | 用途 |
|------|------|
| `capture_turn` | 逐轮上报对话（低延迟  语义搜索关闭时不影响任何现有功能，所有搜索自动 fallback 到关键词匹配。

## 数据源与隐私

用户画像的数据源完全由用户自选。开启越多画像越精准，但隐私暴露也越多：

| 数据源 | 用途 | 隐私级别 |
|--------|------|---------|
| AI 对话 | 推断专注深度、质疑倾向、完美偏好 | 仅本地存储 |
| Git 提交 | 推断续航模式、创新倾向 | 仅统计信息，不存代码 |
| Memos 笔记 | 推断认知风格、知识结构 | 过滤 AI 生成内容，仅存元数据 |
| Wiki 交互 | 推断关注领域、学习路径 | 仅页面路径和动作类型 |
| 微信聊天 | 推断情绪模式、社交偏好 | 仅本地处理，不上传 |

所有数据源默认关闭，用户需主动开启。微信数据源仅在本地处理，不涉及任何第三方服务。

## 技术栈

- **语言**：Python 3.10+
- **存储**：Markdown 文件（知识库）+ SQLite（画像/评分/图谱/调度）
- **协议**：MCP (Model Context Protocol) 用于 AI Agent 集成
- **蒸馏委托**：AgentDelegate（同源复用，不直接调用 LLM API）
- **评分算法**：ComplementNB + TfidfVectorizer + 贝叶斯后验更新
- **聚类算法**：HDBSCAN → DBSCAN → K-Means 回退链
- **调度**：拓扑排序 + ThreadPoolExecutor 并行执行
- **文档处理**：PDF / PPT / Excel / Word / HTML / EBOOK 解析
- **核心依赖**：requests、pyyaml、watchdog、numpy

## 项目状态

**Mnemos v2 beta** — 核心链路可用，高级能力持续完善中。

### beta 已可用（经过代码复查，生产可用）

- [x] **同步框架**：SyncEngine 8 步流水线 + 5 Agent Source + L1 兜底去重 + Memos→Wiki 追溯
- [x] **七层蒸馏流水线**：噪音过滤 → 价值预判 → LLM 判断 → 知识提取 → 自检 → 跨 Agent 关联 → 反馈循环
- [x] **知识图谱**：EntityManager + RelationManager + 置信度治理（source_method 上限）+ 上下文感知查询
- [x] **评分闭环**：COLD/WARM/HOT 三阶段 + 6 子系统评分器 + 训练样本收集 + 漂移检测
- [x] **质量保障**：Freshness 四态检测、Blindspot 降级暴露、Predictive Push relevance gate、搜索弱相关过滤
- [x] **数据治理**：历史截断扫描标记、来源分布统一、KG 关系置信度上限
- [x] **热插拔架构**：14+ 子系统独立启停，故障自动隔离
- [x] **MCP 服务器**：多工具覆盖知识库/摄入/会话/KIA/画像/决策/系统
- [x] **五 Agent 全适配**：Claude Code / Hermes / OpenClaw / OpenCode / Codex

### 持续完善中

- [ ] **评分器冷启动**：需 ≥20 训练样本才能进入 WARM 模式，自然积累中
- [x] **语义搜索（Embedding）**：硅基流动 BAAI/bge-m3，支持向量索引 + 语义召回，现有搜索自动 fallback
- [ ] **Web Dashboard**：可视化知识图谱与画像趋势
- [ ] **Obsidian 插件**：双向同步与内联查询

### 长期能力

- [x] 同源复用设计（AgentDelegate，不直接调用 LLM API）
- [x] 五 Agent 全适配（Claude Code / Hermes / OpenClaw / OpenCode / Codex）
- [x] MCP 服务器（多工具覆盖知识库/摄入/会话/KIA/画像/决策/系统）
- [x] 文档处理（PDF/PPT/Excel/Word/HTML/EBOOK 解析入库）
- [x] 热插拔模块化架构（14+ 子系统独立启停）
- [x] 语义搜索（硅基流动 BAAI/bge-m3，可选启用）
- [ ] Web Dashboard
- [ ] Obsidian 插件

## 致谢

- [Andrej Karpathy](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) —— LLM Wiki 模式的提出者，Mnemos 的核心灵感来源
- [Memos](https://github.com/usememos/memos) —— 优秀的开源笔记系统，Mnemos 的原始资料入口
- [Obsidian](https://obsidian.md) —— 知识管理的标杆工具，Mnemos 推荐的知识库可视化方案

## 许可证

[MIT License](LICENSE)

---

**Mnemos**（/ˈnɛmɒs/）—— 希腊神话中的记忆女神，谟涅摩叙涅。不是帮你记住，而是让你的 AI 全自动地懂得何时该想起、如何该行动。

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [jielumaizui](https://github.com/jielumaizui)
- **Source:** [jielumaizui/Mnemos](https://github.com/jielumaizui/Mnemos)
- **License:** MIT
- **Homepage:** https://github.com/jielumaizui/mnemos

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-jielumaizui-mnemos
- Seller: https://agentstack.voostack.com/s/jielumaizui
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.