内容
<div align="center">
<pre>
███╗ ███╗██╗███╗ ██╗██╗ ██████╗ ███╗ ██╗ ██████╗ ███████╗
████╗ ████║██║████╗ ██║██║██╔═══██╗████╗ ██║██╔═══██╗██╔════╝
██╔████╔██║██║██╔██╗ ██║██║██║ ██║██╔██╗ ██║██║ ██║███████╗
██║╚██╔╝██║██║██║╚██╗██║██║██║ ██║██║╚██╗██║██║ ██║╚════██║
██║ ╚═╝ ██║██║██║ ╚████║██║╚██████╔╝██║ ╚████║╚██████╔╝███████║
╚═╝ ╚═╝╚═╝╚═╝ ╚═══╝╚═╝ ╚═════╝ ╚═╝ ╚═══╝ ╚═════╝ ╚══════╝
</pre>
<p>
<a href="https://github.com/Catafal/MinionOS/actions/workflows/ci.yml">
<img src="https://github.com/Catafal/MinionOS/actions/workflows/ci.yml/badge.svg" alt="持续集成">
</a>
<a href="https://www.python.org/downloads/">
<img src="https://img.shields.io/badge/python-3.11%2B-blue" alt="Python 3.11+">
</a>
<a href="LICENSE">
<img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg" alt="许可证">
</a>
</p>
</div>
> 面向AI代理的本地优先内存
你的AI代理在会话之间会忘记所有内容。 MinionOS可以解决这个问题。 向它提供文本，它会将实体、关系和事实提取到本地SQLite知识图中，然后在代理需要时提供相关上下文。
除非你指定远程LLM，否则不会有任何数据离开你的机器。
---
## 快速开始
```bash
# 安装
python3.11 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
# 设置
memos onboard
# 存储你的第一个记忆
memos remember "与Sarah讨论了Q3路线图。她对时间表感到担忧。" --domain job
# 稍后查找
memos search "路线图"
```
---
## 你可以做的事情
**存储知识** — 馈送任意自由文本，LLM会自动提取实体、关系和事实：
```bash
memos remember "开始阅读DDIA，关于复制的章节" --domain side-projects
memos remember "Jake上周调到了基础设施团队" --domain job
cat meeting-notes.txt | memos remember --stdin --domain job
```
**搜索你的图谱** — BM25 + 图谱增强检索，按领域范围划分：
```bash
memos search "复制"
memos search "Jake" --domain job --limit 5
memos --format json search "Python" | jq '.[].name'
```
**向代理注入上下文** — 将相关实体和最近的事实打包成有效载荷：
```bash
memos context "当前工作" --format json
memos context "Python" --domain job --days 3 --format json | agent --context -
```
**提问** — 获取基于你的知识图谱的答案：
```bash
memos ask "Sarah关于时间表说了什么？"
```
**跟踪趋势** — 查看哪些实体正在上升、稳定或减少：
```bash
memos trends --domain job
```
---
## MCP服务器
`memos-mcp`将知识图谱作为[MCP](https://modelcontextprotocol.io/)工具公开。 任何支持MCP的代理都可以直接读写你的内存。
```bash
memos-mcp
```
将你的MCP兼容代理指向它，它将获得`search`、`remember`、`context`和`ask`等工具。
---
## Obsidian同步
图谱可以作为`.md`实体文件存放在你的Obsidian保险库中。 在Obsidian中编辑，同步回来：
```bash
# 添加你的保险库
memos vault add my-notes ~/Documents/my-notes
# 将保险库编辑同步到SQLite索引
memos sync
# 在相关实体之间插入[[wikilinks]]
memos link
```
你可以注册多个保险库。 每个保险库都映射到一个领域。
---
## 背景小精灵
14个自治工作进程，用于整合事实、链接实体、检测矛盾、修剪过时的边和嵌入事实以进行语义搜索。 它们按计划运行，因此图谱在无需手动干预的情况下保持健康。
```bash
# 一次运行所有维护任务
memos heartbeat run
# 设置自动调度（macOS上的launchd，Linux上的systemd）
memos heartbeat install
# 检查正在运行的内容
memos heartbeat status
```
每个小精灵任务都可以单独在`~/.minionOS/config.yaml`中配置 — 启用/禁用、设置频率、调整心跳间隔。
---
## 使用Ollama（完全本地，无需API密钥）
```bash
ollama serve
ollama pull llama3.1
memos config set llm_base_url http://localhost:11434/v1
memos config set llm_model llama3.1
```
所有内容都保留在你的机器上。 无需API密钥。
---
## 故障排除
首先运行诊断：
```bash
memos doctor # 11项检查：配置、API、数据库、保险库、服务
memos doctor --fix # 自动修复可以修复的问题
```
| 问题 | 解决方法 |
|---------|-----|
| 没有API密钥 | `memos onboard` 或 `export OPENROUTER_API_KEY="sk-or-v1-..."` |
| 数据库丢失 | `memos doctor --fix` 重建数据库 |
| 保险库不同步 | `memos vault list` 验证路径，然后 `memos sync` |
| 心跳不运行 | `memos heartbeat install` |
| LLM提取失败 | 文本会自动排队并在下一个心跳时重试 |
---
## 所有命令
```
memos remember "文本" 通过LLM提取存储知识
memos search "查询" BM25 + 图谱搜索
memos context "主题" 代理注入上下文包
memos ask "问题" 基于图谱的问答
memos trends 实体提及趋势随时间变化
memos recap 最近活动的叙述性总结
memos digest 总结最近的图谱活动
memos onboard 完整引导设置（推荐）
memos init 将保险库添加到现有安装中
memos status 系统状态：配置、保险库、数据库、LLM
memos doctor 健康检查，自动修复
memos vault add/list/remove 管理保险库
memos sync 将保险库编辑同步到SQLite
memos link 在保险库文件中插入[[wikilinks]]
memos heartbeat run 一次运行所有小精灵
memos heartbeat install 调度自动运行
memos dashboard 小精灵状态实时显示
memos integrate 渲染代理集成提示
memos config 查看或修改配置
```
所有命令都支持 `--format json` 以获取机器可读的输出。
---
## 先决条件
| 要求 | 说明 |
|-------------|-------|
| Python 3.11+ | 使用现代类型联合语法 |
| OpenRouter API密钥 | 用于LLM提取。 在[openrouter.ai/keys](https://openrouter.ai/keys)上免费获取。 或使用Ollama本地运行。 |
| Ollama *(可选)* | 完全本地的LLM — 无需API密钥，无需网络调用 |
---
## 开发
### 设置
```bash
git clone https://github.com/Catafal/MinionOS.git
cd MinionOS
python3.11 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
```
### 质量门控
```bash
make gate # ruff + mypy + pytest （每次提交前运行）
make test # pytest 含覆盖率
make fix # 自动修复 lint 和格式化
make lint # ruff 检查 + 格式验证
make type # mypy 严格类型检查
```
### 项目结构
```
MinionOS/
├── src/minionos/
│ ├── cli/ # Click CLI 命令
│ ├── minions/ # 14个自治后台工作进程
│ ├── integrations/ # 代理集成层
│ ├── prompts/ # LLM 提示模板
│ ├── skills/ # 心跳技能定义
│ ├── api.py # 公共API（CLI 和 MCP 调用此API）
│ ├── db.py # SQLite 架构 + 查询
│ ├── retrieval.py # BM25 + 向量 + RRF 排名
│ ├── graph.py # 实体/关系图操作
│ ├── llm.py # LLM 客户端（OpenRouter，Ollama，Gemini）
│ ├── config.py # YAML 配置加载器
│ ├── vault.py # Obsidian 保险库读写
│ └── mcp_server.py # MCP 服务器入口点
├── tests/ # 1,000+ 测试
├── docs/ # 完整文档（Diataxis 框架）
└── memory/decisions/ # 架构决策记录
```
### 面向在此代码库上工作的AI代理
最小读取路径（~2,500个代币总数）：
1. `CLAUDE.md` — 约定、层规则、命令
2. `docs/index.md` — 组件状态 + 快速路由
3. `docs/graph/catalog.yaml` — 完整文档索引
4. 您需要的特定文档
---
## 文档
| 主题 | 文件 |
|-------|------|
| CLI用法（设置、命令、脚本） | [docs/backend/how-to/using-the-cli.md](docs/backend/how-to/using-the-cli.md) |
| CLI命令参考（选项、退出代码） | [docs/backend/reference/cli-reference.md](docs/backend/reference/cli-reference.md) |
| 架构决策 | [memory/decisions/](memory/decisions/) |
| 后端引导式演练 | [docs/books/backend.md](docs/books/backend.md) |
| 所有文档（导航地图） | [docs/backend/NAVIGATION_MAP.md](docs/backend/NAVIGATION_MAP.md) |
| 产品需求 | [PRD.md](PRD.md) |
| 技术栈和版本 | [TECH_STACK.md](TECH_STACK.md) |
| 用户流程和错误处理 | [APP_FLOW.md](APP_FLOW.md) |
---
## 贡献
欢迎贡献。 请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 以了解开发设置、代码风格和PR流程。
## 安全
通过 [GitHub Security Advisories](https://github.com/Catafal/MinionOS/security/advisories/new) 报告漏洞。 有关详细信息，请参阅 [SECURITY.md](SECURITY.md)。
## 许可证
Apache 2.0 — 请参阅 [LICENSE](LICENSE)。
---
**你的代理记住。你不必记住。**
