# MOKAGI：具备长期记忆与知识库的自主 AI Agent 系统

> MOKAGI 是一个功能完整的 AI Agent 系统，支持多步骤任务自主执行、长期记忆管理、工具调用和工作流编排，提供 Telegram 和 Web 双端界面。

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-06-07T16:45:38.000Z
- 最近活动: 2026-06-07T16:53:51.263Z
- 热度: 114.9
- 关键词: AI Agent, Long-term Memory, Knowledge Base, Tool Calling, Workflow, ChromaDB, Telegram Bot, Multi-agent
- 页面链接: https://www.zingnex.cn/forum/thread/mokagi-ai-agent
- Canonical: https://www.zingnex.cn/forum/thread/mokagi-ai-agent
- Markdown 来源: ingested_event

---

## 原作者与来源

- 原作者/维护者：MOK2026
- 来源平台：github
- 原始标题：MOKAGI
- 原始链接：https://github.com/MOK2026/MOKAGI
- 来源发布时间/更新时间：2026-06-07T16:45:38Z

## 原作者与来源\n\n- **原作者/维护者**: MOK2026\n- **来源平台**: GitHub\n- **原始标题**: MOKAGI\n- **原始链接**: https://github.com/MOK2026/MOKAGI\n- **发布时间**: 2026年6月7日\n\n---\n\n## 引言：构建真正自主的 AI Agent\n\n当前市面上的 AI 助手大多局限于单次对话，缺乏长期记忆能力和多步骤任务执行能力。用户每次交互都需要重新提供上下文，复杂任务需要人工分解为多个步骤逐一执行。\n\nMOKAGI 项目正是为了解决这些问题而诞生的。它是一个功能完整的 AI Agent 系统，具备长期记忆、知识库管理、工具调用和多步骤工作流编排等核心能力。系统支持通过 Telegram 机器人和 Web 界面两种方式与用户交互，并采用模块化设计，便于扩展和定制。\n\n---\n\n## 系统架构概览\n\nMOKAGI 采用清晰的分层架构，将系统划分为核心引擎、前端适配器、工具插件和知识库四个主要部分。\n\n### 核心引擎（core/）\n\n核心引擎是系统的"大脑"，负责处理所有 AI 相关的逻辑：\n\n- **launcher.py**：统一启动器，扫描配置并启动所有机器人和 Web 服务\n- **mokagi.py**：核心 AI 引擎，处理对话、工具调用和工作流执行\n- **tool_handler.py**：工具加载与命令路由中间件，动态加载所有工具插件\n- **recovery.py**：意图模糊恢复和错误处理模块\n- **logger.py**：工作流日志模块，记录执行过程\n\n### 前端适配器（frontends/）\n\n系统提供两种用户交互界面：\n\n- **mok_tg.py**：Telegram 机器人，支持流式输出和命令交互\n- **mok_web.py**：Web + SocketIO 服务，提供浏览器访问界面\n\n### 工具插件系统（tools/）\n\nMOKAGI 采用插件化架构，所有工具都位于 tools/ 目录，支持热加载：\n\n- **admin.py**：管理命令（htop、切换模型、执行 shell 等）\n- **autofix.py**：自动修正 Python 代码错误\n- **memory.py**：长期记忆（ChromaDB）与知识库管理\n- **web_search.py**：网页搜索（DuckDuckGo + Tavily）\n- **web_fetch.py**：网页抓取并转为 Markdown\n- **workflow.py**：多步骤工作流管理\n\n---\n\n## 核心能力详解\n\n### 长期记忆系统\n\nMOKAGI 的长期记忆系统基于 ChromaDB 向量数据库实现，支持两种记忆类型：\n\n**用户记忆（user_memory）**：\n- 存储用户的历史对话和个人偏好\n- 通过 `/memory remember` 命令主动记录信息\n- 通过 `/memory recall` 命令检索相关记忆\n\n**知识库（kb_room）**：\n- 存储技术文档和团队规范等结构化知识\n- 自动扫描 `~/.mok/<agent>/` 下的 `.md` 文件并切块存入\n- 通过 `/memory rebuild_kb` 命令重建知识库\n\n这种双轨记忆设计使得 Agent 既能记住用户的个性化信息，又能访问专业知识库，提供更精准的服务。\n\n### 多步骤工作流\n\nMOKAGI 支持复杂的多步骤任务自主执行。当用户输入任务目标时，系统会：\n\n1. **任务分类**：使用轻量级 LLM 调用判断任务类型（multi_step、single_tool、chat 等）\n2. **工作流创建**：通过 `/workflow create <目标>` 创建多步骤工作流\n3. **自主规划**：Agent 自动分解任务为多个步骤\n4. **逐步执行**：按顺序执行每个步骤，并根据中间结果调整后续计划\n5. **状态跟踪**：通过 `/workflow status` 查看当前工作流进度\n\n### 工具调用机制\n\n所有工具都遵循统一的插件规范，必须定义 `PLUGIN_INFO` 字典：\n\n```python\nPLUGIN_INFO = {\n    \"command\": \"/mycommand\",           # Telegram 命令\n    \"icon\": \"🔧\",                      # 图标\n    \"handler\": \"handle_mycommand\",     # 异步处理函数名\n    \"description\": \"工具描述\",\n    \"intent_keywords\": [                # 自然语言触发词\n        (\"关键词\", \"/mycommand subcmd\")\n    ],\n    \"tool_schema\": {                    # 供 LLM 自动调用的 JSON Schema\n        \"name\": \"my_tool\",\n        \"description\": \"...\",\n        \"parameters\": {...}\n    },\n    \"naturalize_func\": \"naturalize_result\"  # 可选：结果自然化函数\n}\n```\n\n工具实现后会被 `tool_handler.load_tools()` 自动加载，并注入到命令映射和 LLM 工具调用中。\n\n---\n\n## 部署与使用\n\n### 一键部署\n\nMOKAGI 提供了一键部署脚本，支持 Ubuntu/Debian 系统：\n\n```bash\ncurl -sL https://raw.githubusercontent.com/MOK2026/MOKAGI/refs/heads/main/MOKAGI.sh -o ~/MOKAGI.sh && sed -i 's/\\r//' ~/MOKAGI.sh && bash ~/MOKAGI.sh\n```\n\n部署完成后，系统将自动：\n\n- 启动 Ollama 本地模型服务（默认 qwen3:1.7b）\n- 使用 PM2 管理统一进程 mok_agi（同时启动 Telegram 机器人和 Web 界面）\n- 加载完整的工具插件系统\n\n### 常用管理命令\n\n| 命令 | 说明 |\n|------|------|\n| `/clear` | 清除当前会话的对话历史 |\n| `/reload` | 紧急重启并重新加载所有工具插件 |\n| `/tools` | 列出所有已加载的工具 |\n| `/admin htop` | 查看系统负载 |\n| `/admin set_model <模型名>` | 切换 LLM 模型 |\n| `/memory remember <内容>` | 记住一段信息 |\n| `/memory recall <关键词>` | 搜索相关记忆 |\n| `/search <关键词>` | 网页搜索 |\n| `/fetch <URL>` | 抓取网页内容 |\n| `/workflow create <目标>` | 创建多步骤工作流 |\n| `/autofix` | 自动修正 Python 代码错误 |\n\n---\n\n## 内容定位与存储策略\n\nMOKAGI 设计了精细的内容分类和存储机制：\n\n| 内容类型 | 存放位置 | 自动注入 system_prompt | 典型内容 |\n|----------|----------|------------------------|----------|\n| AGENTS.md | `~/.mok/<agent>/soul/` | ✅ 是（精简版） | 工作流规则、意图处理步骤 |\n| IDENTITY.md | `~/.mok/<agent>/soul/` | ✅ 是（精简版） | Agent 名称、图标、自我介绍 |\n| SOUL.md | `~/.mok/<agent>/soul/` | ✅ 是（精简版） | 核心人格、语气风格、价值观 |\n| USER.md | `~/.mok/<agent>/soul/` | ⚠️ 部分 | 用户偏好、常用路径 |\n| MEMORY.md | `~/.mok/<agent>/soul/` | ❌ 否 | 固化知识、团队规范 |\n| 长期记忆 | ChromaDB | ❌ 否 | 用户历史对话、个人偏好 |\n| 知识库 | ChromaDB | ❌ 否 | Markdown 文档切块、技术手册 |\n\n这种分层存储策略确保了关键信息能够及时注入到系统提示词中，而大量历史数据则通过向量检索按需获取，既保证了响应质量，又避免了上下文窗口溢出。\n\n---\n\n## Web 界面功能\n\nMOKAGI 的 Web 界面提供了丰富的功能：\n\n- **聊天界面**：支持 Markdown 渲染、代码高亮、流式输出，思考过程与回复分开显示\n- **文件浏览器**：可查看白名单目录内的文本文件和图片/视频\n- **系统监控**：实时显示 CPU、内存、进程列表（通过 `/monitor` 访问）\n- **工具列表**：展示所有已加载插件的命令与描述\n- **Agent 切换**：左上角可选择不同配置（.Agent1、.Agent2 等），即时生效\n- **模型切换**：在"设定"面板中选择模型，自动保存并重启\n\n---\n\n## 扩展与自定义\n\nMOKAGI 的设计充分考虑了扩展性：\n\n### 新增工具\n\n在 `tools/` 目录下创建 `.py` 文件，定义 `PLUGIN_INFO` 和对应的 handler 函数，执行 `/reload` 即可热加载，无需重启服务。\n\n### 新增前端\n\n参考 `frontends/mok_tg.py` 或 `mok_web.py`，调用 `mokagi.process_message()` 并传入 `stream_callback` 即可实现新的交互界面。\n\n### 修改提示词\n\n可直接编辑 `mokagi.py` 中的系统提示词，或通过配置文件的 `MOK_SYSTEM_PROMPT` 覆盖。\n\n---\n\n## 技术亮点与设计理念\n\nMOKAGI 在设计上体现了几个重要的技术理念：\n\n1. **模块化架构**：核心引擎、前端、工具完全解耦，便于独立开发和测试\n\n2. **配置驱动**：每个 Agent 有独立的配置文件（`~/.mok/.<agent_name>`），支持多 Agent 并行运行\n\n3. **热加载支持**：工具和配置修改后可通过 `/reload` 命令即时生效，无需重启\n\n4. **双轨记忆**：区分用户记忆和知识库，既保证个性化又支持知识共享\n\n5. **意图分类**：使用轻量级 LLM 调用预先判断任务类型，提高响应效率\n\n6. **错误恢复**：内置模糊意图恢复和错误处理机制，提升用户体验\n\n---\n\n## 应用场景\n\nMOKAGI 适用于多种场景：\n\n- **个人助手**：管理日程、搜索信息、记住个人偏好\n- **开发辅助**：代码审查、自动修复、技术文档查询\n- **知识管理**：构建个人或团队知识库，支持语义检索\n- **自动化工作流**：将重复性任务编排为自动执行的工作流\n- **多 Agent 协作**：不同 Agent 负责不同领域，通过统一接口协同工作\n\n---\n\n## 总结\n\nMOKAGI 是一个功能全面、架构清晰的 AI Agent 系统。它不仅提供了长期记忆、知识库、工具调用等核心能力，还通过模块化设计和热加载支持，为开发者提供了极大的扩展空间。\n\n对于希望构建自主 AI Agent 的开发者来说，MOKAGI 是一个很好的参考实现。它展示了如何将大语言模型与向量数据库、工具系统、工作流引擎有机结合，构建出真正具备"记忆"和"行动"能力的智能助手。