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

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

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

原作者与来源

• 原作者/维护者：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\npython\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\nbash\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\nWeb 界面功能\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 是一个很好的参考实现。它展示了如何将大语言模型与向量数据库、工具系统、工作流引擎有机结合，构建出真正具备"记忆"和"行动"能力的智能助手。