From 5f42fed8e09ae730d57fdf2f64f2ab2b06b2c6cb Mon Sep 17 00:00:00 2001 From: Acbox Liu Date: Sun, 29 Mar 2026 20:30:21 +0800 Subject: [PATCH] docs: v0.6 (#304) * docs: v0.6 * docs: update readme --- README.md | 56 +++-- README_CN.md | 65 ++--- docs/docs/.vitepress/en.ts | 50 ++-- docs/docs/about.md | 58 +++-- docs/docs/channels/discord.md | 2 +- docs/docs/channels/feishu.md | 2 +- docs/docs/channels/index.md | 9 +- docs/docs/channels/matrix.md | 48 ++++ docs/docs/channels/qq.md | 6 +- docs/docs/channels/telegram.md | 6 +- docs/docs/channels/wecom.md | 40 +++ docs/docs/channels/weixin.md | 34 +++ docs/docs/getting-started/access.md | 109 ++++---- docs/docs/getting-started/bot.md | 57 +++-- docs/docs/getting-started/browser.md | 2 +- docs/docs/getting-started/channels.md | 15 +- docs/docs/getting-started/compaction.md | 75 ++++++ docs/docs/getting-started/container.md | 37 ++- docs/docs/getting-started/mcp.md | 34 ++- docs/docs/getting-started/memory.md | 36 ++- .../getting-started/provider-and-model.md | 25 +- docs/docs/getting-started/search-provider.md | 2 +- docs/docs/getting-started/sessions.md | 85 +++++++ docs/docs/getting-started/slash-commands.md | 238 ++++++++++++++++++ docs/docs/getting-started/subagents.md | 38 --- docs/docs/index.md | 6 +- docs/docs/installation/docker.md | 62 +++-- docs/docs/memory-providers/builtin.md | 2 +- docs/docs/memory-providers/index.md | 4 +- docs/docs/memory-providers/mem0.md | 2 +- docs/docs/memory-providers/openviking.md | 2 +- docs/docs/tts-providers/edge.md | 2 +- docs/docs/tts-providers/index.md | 2 +- 33 files changed, 945 insertions(+), 266 deletions(-) create mode 100644 docs/docs/channels/matrix.md create mode 100644 docs/docs/channels/wecom.md create mode 100644 docs/docs/channels/weixin.md create mode 100644 docs/docs/getting-started/compaction.md create mode 100644 docs/docs/getting-started/sessions.md create mode 100644 docs/docs/getting-started/slash-commands.md delete mode 100644 docs/docs/getting-started/subagents.md diff --git a/README.md b/README.md index 9d60b31f..1680a649 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@
Memoh

Memoh

-

Multi-Member, Structured Long-Memory, Containerized AI Agent System.

+

Self hosted, always-on AI agent platform run in containers.

📌 Introduction to Memoh - The Case for an Always-On, Containerized Home Agent

Version @@ -28,7 +28,7 @@
-Memoh is an always-on, containerized AI agent system. Create multiple AI bots, each running in its own isolated container with persistent memory, and interact with them across Telegram, Discord, Lark (Feishu), Email, or the built-in Web UI. Bots can execute commands, edit files, browse the web, call external tools via MCP, and remember everything — like giving each bot its own computer and brain. +Memoh is an always-on, containerized AI agent system. Create multiple AI bots, each running in its own isolated container with persistent memory, and interact with them across Telegram, Discord, Lark (Feishu), QQ, Matrix, WeCom, WeChat, Email, or the built-in Web UI. Bots can execute commands, edit files, browse the web, call external tools via MCP, and remember everything — like giving each bot its own computer and brain. ## Quick Start @@ -52,7 +52,7 @@ sudo docker compose up -d > **Install a specific version:** > ```bash -> curl -fsSL https://memoh.sh | sudo MEMOH_VERSION=v1.0.0 sh +> curl -fsSL https://memoh.sh | sudo MEMOH_VERSION=v0.6.0 sh > ``` > > **Use CN mirror for slow image pulls:** @@ -68,32 +68,36 @@ See [DEPLOYMENT.md](DEPLOYMENT.md) for custom configuration and production setup ## Why Memoh? -OpenClaw is impressive, but it has notable drawbacks: stability issues, security concerns, cumbersome configuration, and high token costs. If you're looking for a stable, secure solution, consider Memoh. +Memoh is built for **always-on continuity** — an AI that stays online, and a memory that stays yours. -Memoh is a multi-bot agent service built with Golang. It offers full graphical configuration for bots, Channels, MCP, and Skills. We use Containerd to provide container-level isolation for each bot and draw heavily from OpenClaw's Agent design. - -Memoh Bot can distinguish and remember requests from multiple humans and bots, working seamlessly in any group chat. You can use Memoh to build bot teams, or set up accounts for family members to manage daily household tasks with bots. +- **Lightweight & Fast**: Built with Go as home/studio infrastructure, runs efficiently on edge devices. +- **Containerized by default**: Each bot gets an isolated container with its own filesystem, network, and tools. +- **Hybrid split**: Cloud inference for frontier model capability, local-first memory and indexing for privacy. +- **Multi-user first**: Explicit sharing and privacy boundaries across users and bots. +- **Full graphical configuration**: Configure bots, channels, MCP, skills, and all settings through a modern web UI — no coding required. ## Features -- 🤖 **Multi-Bot Management**: Create multiple bots; humans and bots, or bots with each other, can chat privately, in groups, or collaborate. Supports role-based access control (owner / admin / member) with ownership transfer. -- 👥 **Multi-User & Identity Recognition**: Bots can distinguish individual users in group chats, remember each person's context separately, and send direct messages to specific users. Cross-platform identity binding unifies the same person across Telegram, Discord, Lark, and Web. -- 📦 **Containerized**: Each bot runs in its own isolated containerd container. Bots can freely execute commands, edit files, and access the network within their containers — like having their own computer. Supports container snapshots for save/restore. -- 🧠 **Memory Engineering**: Multi-provider memory architecture — Built-in (off / sparse / dense modes), [Mem0](https://mem0.ai), and OpenViking. LLM-driven fact extraction, hybrid retrieval (dense semantic search + BM25 keyword + neural sparse vectors), 24-hour context loading, memory compaction & rebuild, and multi-language auto-detection. -- 💬 **Multi-Platform**: Supports Telegram, Discord, Lark (Feishu), Email, and the built-in Web UI. Unified message format with rich text, media attachments, reactions, and streaming across all platforms. Cross-platform identity binding. -- 📧 **Email**: Multi-adapter email service (Mailgun, generic SMTP) with per-bot binding and outbound audit log. Bots can send and receive emails as a channel. -- 🔧 **MCP (Model Context Protocol)**: Full MCP support (HTTP / SSE / Stdio). Built-in tools for container operations, memory search, web search, scheduling, messaging, and more. Connect external MCP servers for extensibility. -- 🧩 **Subagents**: Create specialized sub-agents per bot with independent context and skills, enabling multi-agent collaboration. -- 🎭 **Skills & Identity**: Define bot personality via IDENTITY.md, SOUL.md, and modular skill files that bots can enable/disable at runtime. -- 🌐 **Browser**: Each bot can have its own headless Chromium browser (via Playwright). Navigate pages, click elements, fill forms, take screenshots (with annotated element labels), read accessibility trees, manage tabs, and more — enabling real web automation and AI-driven browsing. -- 🔍 **Web Search**: 12 built-in search providers — Brave, Bing, Google, Tavily, DuckDuckGo, SearXNG, Serper, Sogou, Jina, Exa, Bocha, and Yandex — for web search and URL content fetching. -- ⏰ **Scheduled Tasks**: Cron-based scheduling with max-call limits. Bots can autonomously run commands or tools at specified intervals. -- 💓 **Heartbeat**: Periodic autonomous tasks — bots can perform routine operations (e.g., check-ins, summaries, monitoring) at configurable intervals with execution logging. -- 📥 **Inbox**: Cross-channel inbox — messages from other channels are queued and surfaced in the system prompt so the bot never misses context. -- 📊 **Token Usage Tracking**: Monitor token consumption per bot with usage statistics and visualization. -- 🧪 **Multi-Model**: Works with any OpenAI-compatible, Anthropic, or Google Generative AI provider. Per-bot model assignment for chat, memory, and embedding. -- 🖥️ **Web UI**: Modern dashboard (Vue 3 + Tailwind CSS) with real-time streaming chat, tool call visualization, in-chat file manager, container filesystem browser, and visual configuration for all settings. Dark/light theme, i18n. -- 🚀 **One-Click Deploy**: Docker Compose with automatic migration, containerd setup, and CNI networking. Interactive install script included. +### Core + +- 🤖 **Multi-Bot & Multi-User**: Create multiple bots that chat privately, in groups, or with each other. Bots distinguish individual users in group chats, remember each person's context, and support cross-platform identity binding. +- 📦 **Containerized**: Each bot runs in its own isolated containerd container with a dedicated filesystem and network — like having its own computer. Supports snapshots, data export/import, and versioning. +- 🧠 **Memory Engineering**: LLM-driven fact extraction, hybrid retrieval (dense + sparse + BM25), 24-hour context loading, memory compaction & rebuild. Pluggable backends: Built-in (off / sparse / dense), [Mem0](https://mem0.ai), OpenViking. +- 💬 **9 Channels**: Telegram, Discord, Lark (Feishu), QQ, Matrix, WeCom, WeChat, Email (Mailgun / SMTP / Gmail OAuth), and built-in Web UI — with unified streaming, rich text, and attachments. + +### Agent Capabilities + +- 🔧 **MCP (Model Context Protocol)**: Full MCP support (HTTP / SSE / Stdio / OAuth). Connect external tool servers for extensibility; each bot manages its own independent MCP connections. +- 🌐 **Browser Automation**: Headless Chromium/Firefox via Playwright — navigate, click, fill forms, screenshot, read accessibility trees, manage tabs. +- 🎭 **Skills & Subagents**: Define bot personality via modular skill files; delegate complex tasks to sub-agents with independent context. +- ⏰ **Automation**: Cron-based scheduled tasks and periodic heartbeat for autonomous bot activity. + +### Management + +- 🖥️ **Web UI**: Modern dashboard (Vue 3 + Tailwind CSS) — streaming chat, tool call visualization, file manager, visual configuration for all settings. Dark/light theme, i18n. +- 🔐 **Access Control**: Priority-based ACL rules with allow/deny effects, scoped by channel identity, channel type, or conversation. +- 🧪 **Multi-Model**: Any OpenAI-compatible, Anthropic, or Google provider. Per-bot model assignment, provider OAuth, and automatic model import. +- 🚀 **One-Click Deploy**: Docker Compose with automatic migration, containerd setup, and CNI networking. ## Memory System @@ -140,7 +144,7 @@ Additional capabilities include memory compaction (merge redundant entries), reb flowchart TB subgraph Clients [" Clients "] direction LR - CH["Channels
Telegram · Discord · Feishu · QQ · Email"] + CH["Channels
Telegram · Discord · Feishu · QQ
Matrix · WeCom · WeChat · Email"] WEB["Web UI (Vue 3 :8082)"] end diff --git a/README_CN.md b/README_CN.md index 65117874..4cc3641a 100644 --- a/README_CN.md +++ b/README_CN.md @@ -6,7 +6,7 @@
Memoh

Memoh

-

多成员、结构化长记忆、容器化的 AI Agent 系统。

+

自托管、常驻运行的容器化 AI Agent 平台。

📌 Introduction to Memoh - The Case for an Always-On, Containerized Home Agent

Version @@ -28,7 +28,7 @@
-Memoh 是一个常驻运行的容器化 AI Agent 系统。你可以创建多个 AI 机器人，每个机器人运行在独立的容器中，拥有持久化记忆，并通过 Telegram、Discord、飞书(Lark)、Email 或内置 Web 管理界面与之交互。机器人可以执行命令、编辑文件、浏览网页、通过 MCP 调用外部工具，并记住一切 —— 就像给每个 Bot 一台自己的电脑和大脑。 +Memoh 是一个常驻运行的容器化 AI Agent 系统。你可以创建多个 AI 机器人，每个机器人运行在独立的容器中，拥有持久化记忆，并通过 Telegram、Discord、飞书(Lark)、QQ、Matrix、企业微信、微信、Email 或内置 Web 界面与之交互。机器人可以执行命令、编辑文件、浏览网页、通过 MCP 调用外部工具，并记住一切 —— 就像给每个 Bot 一台自己的电脑和大脑。 ## 快速开始 @@ -45,12 +45,14 @@ curl -fsSL https://memoh.sh | sudo sh ```bash git clone --depth 1 https://github.com/memohai/Memoh.git cd Memoh +cp conf/app.docker.toml config.toml +# 编辑 config.toml sudo docker compose up -d ``` > **安装指定版本：** > ```bash -> curl -fsSL https://memoh.sh | sudo MEMOH_VERSION=v1.0.0 sh +> curl -fsSL https://memoh.sh | sudo MEMOH_VERSION=v0.6.0 sh > ``` > > **使用中国大陆镜像加速：** @@ -66,36 +68,40 @@ sudo docker compose up -d ## 为什么选择 Memoh？ -OpenClaw 令人印象深刻，但在稳定性、安全性、配置复杂度和 token 成本上存在明显不足。如果你正在寻找稳定、安全的方案，不妨考虑 Memoh。 +Memoh 为**常驻连续运行**而生 —— 一个始终在线的 AI，一份属于你自己的记忆。 -Memoh 是基于 Golang 的多 bot agent 服务，提供 bot、Channel、MCP、Skills 等的完整图形化配置。我们使用 Containerd 为每个 bot 提供容器级隔离，并大量借鉴 OpenClaw 的 Agent 设计。 - -Memoh Bot 能区分并记忆多人与多 bot 的请求，在任意群聊中无缝协作。你可以用 Memoh 组建 bot 团队，或为家人配置账号，用 bot 管理日常家务。 +- **轻量高效**：Go 语言构建，可作为家庭/工作室基础设施，在边缘设备上高效运行。 +- **默认容器化**：每个 Bot 拥有独立容器，包含专属文件系统、网络和工具。 +- **混合架构**：云端推理获取前沿模型能力，本地记忆和索引保障隐私。 +- **多用户优先**：用户与 Bot 之间具有明确的共享和隐私边界。 +- **全图形化配置**：通过现代 Web 界面配置 Bot、渠道、MCP、技能等所有设置，无需编写代码。 ## 特性 -- 🤖 **多 Bot 管理**：创建多个 bot；人与 bot、bot 与 bot 可私聊、群聊或协作。支持角色权限控制（owner / admin / member）与所有权转让。 -- 👥 **多用户与身份识别**：Bot 可在群聊中区分不同用户，分别记忆每个人的上下文，并支持向特定用户单独发送消息。跨平台身份绑定将同一用户在 Telegram、Discord、飞书、Web 上的身份统一关联。 -- 📦 **容器化**：每个 bot 运行在独立的 containerd 容器中，可在容器内自由执行命令、编辑文件、访问网络，宛如各自拥有一台电脑。支持容器快照保存与恢复。 -- 🧠 **记忆工程**：多供应商记忆架构 —— 内置（off / sparse / dense 三种模式）、[Mem0](https://mem0.ai)、OpenViking。LLM 驱动的知识抽取，混合检索（稠密语义搜索 + BM25 关键词 + 神经稀疏向量），24 小时上下文加载，记忆压缩与重建，多语言自动检测。 -- 💬 **多平台**：支持 Telegram、Discord、飞书(Lark)、Email 及内置 Web 管理界面。跨平台统一消息格式，支持富文本、媒体附件、表情回应和流式输出。跨平台身份绑定。 -- 📧 **邮件**：多适配器邮件服务（Mailgun、通用 SMTP），支持按 bot 绑定与发信审计日志。Bot 可将邮件作为渠道收发。 -- 🔧 **MCP（模型上下文协议）**：完整 MCP 支持（HTTP / SSE / Stdio）。内置容器操作、记忆搜索、网络搜索、定时任务、消息发送等工具，可连接外部 MCP 服务器扩展。 -- 🧩 **子代理**：为每个 bot 创建专用子代理，拥有独立上下文与技能，实现多代理协作。 -- 🎭 **技能与身份**：通过 IDENTITY.md、SOUL.md 定义 bot 人格，模块化技能文件可在运行时启用/禁用。 -- 🌐 **浏览器**：每个 Bot 可拥有独立的无头 Chromium 浏览器（基于 Playwright）。支持页面导航、点击、填写表单、截图（带编号标注的交互元素）、读取无障碍树、多标签页管理等，实现真正的网页自动化与 AI 驱动浏览。 -- 🔍 **网络搜索**：内置 12 种搜索提供商 —— Brave、Bing、Google、Tavily、DuckDuckGo、SearXNG、Serper、搜狗、Jina、Exa、Bocha、Yandex，支持网页搜索与 URL 内容抓取。 -- ⏰ **定时任务**：基于 Cron 的任务调度，支持最大调用次数限制。Bot 可自主在指定时间执行命令或工具。 -- 💓 **心跳**：周期性自主任务，Bot 可按配置间隔执行例行操作（如签到、汇总、监控），并记录执行日志。 -- 📥 **收件箱**：跨渠道收件箱，其他渠道的消息会排入收件箱并呈现在系统提示词中，确保 bot 不遗漏上下文。 -- 📊 **Token 用量追踪**：按 bot 监控 token 消耗，支持用量统计与可视化。 -- 🧪 **多模型**：兼容任何 OpenAI 兼容、Anthropic 或 Google Generative AI 提供商。每个 bot 可独立配置聊天、记忆和嵌入模型。 -- 🖥️ **Web 管理界面**：基于 Vue 3 + Tailwind CSS 的现代面板，实时流式聊天、工具调用可视化、聊天内文件管理器、容器文件浏览器，所有配置可视化操作。深色/浅色主题，中英文支持。 -- 🚀 **一键部署**：Docker Compose 编排，自动迁移、containerd 初始化与 CNI 网络配置。附带交互式安装脚本。 +### 核心 + +- 🤖 **多 Bot 与多用户**：创建多个 Bot，支持私聊、群聊或 Bot 间协作。Bot 可在群聊中区分不同用户，分别记忆上下文，并支持跨平台身份绑定。 +- 📦 **容器化**：每个 Bot 运行在独立的 containerd 容器中，拥有专属文件系统和网络，宛如各自拥有一台电脑。支持快照、数据导入/导出与版本管理。 +- 🧠 **记忆工程**：LLM 驱动的知识抽取，混合检索（稠密 + 稀疏 + BM25），24 小时上下文加载，记忆压缩与重建。可插拔后端：内置（off / sparse / dense）、[Mem0](https://mem0.ai)、OpenViking。 +- 💬 **9 大渠道**：Telegram、Discord、飞书(Lark)、QQ、Matrix、企业微信、微信、Email（Mailgun / SMTP / Gmail OAuth）及内置 Web 界面 —— 统一流式输出、富文本和附件支持。 + +### Agent 能力 + +- 🔧 **MCP（模型上下文协议）**：完整 MCP 支持（HTTP / SSE / Stdio / OAuth）。连接外部工具服务器进行扩展，每个 Bot 独立管理自己的 MCP 连接。 +- 🌐 **浏览器自动化**：基于 Playwright 的无头 Chromium/Firefox —— 页面导航、点击、填写表单、截图、读取无障碍树、多标签页管理。 +- 🎭 **技能与子代理**：通过模块化技能文件定义 Bot 人格；将复杂任务委派给拥有独立上下文的子代理。 +- ⏰ **自动化**：基于 Cron 的定时任务和周期性心跳，实现 Bot 自主活动。 + +### 管理 + +- 🖥️ **Web 界面**：基于 Vue 3 + Tailwind CSS 的现代面板 —— 流式聊天、工具调用可视化、文件管理器、所有配置可视化操作。深色/浅色主题，中英文支持。 +- 🔐 **访问控制**：基于优先级的 ACL 规则，支持 allow/deny 效果，可按渠道身份、渠道类型或会话维度控制。 +- 🧪 **多模型**：兼容任何 OpenAI 兼容、Anthropic 或 Google 提供商。每个 Bot 独立配置模型，支持 Provider OAuth 和自动模型导入。 +- 🚀 **一键部署**：Docker Compose 编排，自动迁移、containerd 初始化与 CNI 网络配置。 ## 记忆系统 -Memoh 的记忆系统围绕 **Memory Provider（记忆供应商）** 构建 —— 可插拔的后端，控制 bot 如何存储、检索和管理长期记忆。 +Memoh 的记忆系统围绕 **Memory Provider（记忆供应商）** 构建 —— 可插拔的后端，控制 Bot 如何存储、检索和管理长期记忆。 | 供应商 | 说明 | |--------|------| @@ -103,7 +109,7 @@ Memoh 的记忆系统围绕 **Memory Provider（记忆供应商）** 构建 — | **Mem0** | 通过 [Mem0](https://mem0.ai) API 的 SaaS 记忆服务。 | | **OpenViking** | 自托管或 SaaS 记忆服务，使用自有 API。 | -每个 bot 绑定一个供应商。聊天过程中，bot 自动从每轮对话中抽取关键事实并存储为结构化记忆。收到新消息时，系统通过混合检索找到最相关的记忆并注入 bot 上下文 —— 实现跨对话的个性化长期记忆。 +每个 Bot 绑定一个供应商。聊天过程中，Bot 自动从每轮对话中抽取关键事实并存储为结构化记忆。收到新消息时，系统通过混合检索找到最相关的记忆并注入 Bot 上下文 —— 实现跨对话的个性化长期记忆。 其他功能包括记忆压缩（合并冗余条目）、重建、手动创建/编辑，以及向量流形可视化（Top-K 分布与 CDF 曲线）。详见[文档](https://docs.memoh.ai/memory-providers/)。 @@ -132,15 +138,14 @@ Memoh 的记忆系统围绕 **Memory Provider（记忆供应商）** 构建 — - ## 架构 ```mermaid flowchart TB subgraph Clients [" 客户端 "] direction LR - CH["渠道
Telegram · Discord · 飞书 · QQ · Email"] - WEB["Web 管理界面 (Vue 3 :8082)"] + CH["渠道
Telegram · Discord · 飞书 · QQ
Matrix · 企业微信 · 微信 · Email"] + WEB["Web 界面 (Vue 3 :8082)"] end CH & WEB --> API diff --git a/docs/docs/.vitepress/en.ts b/docs/docs/.vitepress/en.ts index b567e235..890a9849 100644 --- a/docs/docs/.vitepress/en.ts +++ b/docs/docs/.vitepress/en.ts @@ -21,48 +21,52 @@ export const en = [ text: 'Getting Started', items: [ { - text: 'LLM Provider and Model', + text: 'LLM Provider', link: '/getting-started/provider-and-model.md' }, { - text: 'Bot Management', + text: 'Bot', link: '/getting-started/bot.md' }, { - text: 'Bot Access Control', + text: 'Sessions', + link: '/getting-started/sessions.md' + }, + { + text: 'Access Control', link: '/getting-started/access.md' }, { - text: 'Container Management', + text: 'Container', link: '/getting-started/container.md' }, { - text: 'Files Management', + text: 'Files', link: '/getting-started/files.md' }, { - text: 'Bot Skills', + text: 'Skills', link: '/getting-started/skills.md' }, { - text: 'MCP Connections', + text: 'MCP', link: '/getting-started/mcp.md' }, { - text: 'Bot Channels', + text: 'Channels', link: '/getting-started/channels.md' }, { - text: 'Browser Contexts', + text: 'Browser', link: '/getting-started/browser.md' }, { - text: 'Memory Management', + text: 'Memory', link: '/getting-started/memory.md' }, { - text: 'Subagents', - link: '/getting-started/subagents.md' + text: 'Context Compaction', + link: '/getting-started/compaction.md' }, { text: 'Heartbeat', @@ -73,13 +77,17 @@ export const en = [ link: '/getting-started/schedule.md' }, { - text: 'Search Providers', + text: 'Web Search', link: '/getting-started/search-provider.md' }, { - text: 'Email Providers', + text: 'Email', link: '/getting-started/email.md' }, + { + text: 'Slash Commands', + link: '/getting-started/slash-commands.md' + }, ] }, { @@ -139,6 +147,18 @@ export const en = [ text: 'QQ', link: '/channels/qq.md' }, + { + text: 'Matrix', + link: '/channels/matrix.md' + }, + { + text: 'WeCom (WeWork)', + link: '/channels/wecom.md' + }, + { + text: 'WeChat', + link: '/channels/weixin.md' + }, ] }, -] \ No newline at end of file +] diff --git a/docs/docs/about.md b/docs/docs/about.md index bf69958c..ce17b786 100644 --- a/docs/docs/about.md +++ b/docs/docs/about.md @@ -2,13 +2,13 @@ ## What is Memoh? -Memoh is a multi-member, structured long-memory, containerized AI agent system platform. You can create your own AI bots and chat with them via Telegram, Discord, Lark (Feishu), Email, or Web. Every bot has an independent container and memory system, allowing it to edit files, execute commands, and access the network within its own container — like having its own computer and brain. +Memoh is a multi-member, structured long-memory, containerized AI agent system platform. You can create your own AI bots and chat with them via Telegram, Discord, Lark (Feishu), QQ, Matrix, WeCom, WeChat, Email, or Web. Every bot has an independent container and memory system, allowing it to edit files, execute commands, and access the network within its own container — like having its own computer and brain. ## Key Features ### Multi-Bot Management -Create multiple bots. Humans and bots, or bots with each other, can chat privately, in groups, or collaborate. Supports role-based access control (owner / admin / member) with ownership transfer. Build bot teams, or set up accounts for family members to manage daily tasks with bots. +Create multiple bots. Humans and bots, or bots with each other, can chat privately, in groups, or collaborate. Build bot teams, or set up accounts for family members to manage daily tasks with bots. ### Multi-User & Identity Recognition @@ -16,15 +16,14 @@ Bots can distinguish individual users in group chats, remember each person's con ### Containerized Isolation -Each bot runs in its own isolated container (powered by Containerd) with a separate filesystem and network. Bots can freely read/write files and execute commands within their containers without interfering with each other. Supports container snapshots for save/restore. +Each bot runs in its own isolated container (powered by Containerd) with a separate filesystem and network. Bots can freely read/write files and execute commands within their containers without interfering with each other. Supports container snapshots for save/restore, data export/import, and versioning. ### Memory Engineering -A deeply engineered, multi-provider memory layer: +A deeply engineered memory layer: -- **Multi-provider architecture**: Built-in (with off/sparse/dense modes), Mem0 (SaaS), and OpenViking (self-hosted or SaaS) - Automatically extracts key facts from each conversation turn and stores them as structured memories -- Hybrid retrieval: semantic search (via Qdrant vector database) + keyword retrieval (BM25) + neural sparse vectors +- Hybrid retrieval: semantic search (via Qdrant vector database) + keyword retrieval (BM25) - Loads the last 24 hours of conversation context by default - Automatic memory compaction and rebuild capabilities - Multi-language auto-detection @@ -36,7 +35,11 @@ Unified channel adapter architecture for connecting to multiple messaging platfo - **Telegram** — Full support with streaming, Markdown, attachments, and replies - **Discord** — Full support - **Lark (Feishu)** — Full support -- **Email** — Inbound webhook + outbound providers (Mailgun, generic SMTP) +- **QQ** — Full support +- **Matrix** — Decentralized messaging protocol support +- **WeCom (WeWork)** — Enterprise messaging integration +- **WeChat** — Personal messaging via the WeChat AI bot platform +- **Email** — Inbound webhook + outbound providers (Mailgun, generic SMTP, Gmail OAuth) - **Web** — Built-in web chat interface with streaming ### Agent Capabilities @@ -44,13 +47,40 @@ Unified channel adapter architecture for connecting to multiple messaging platfo Bots come with a rich set of built-in tools: - **Web Search** — Configurable search providers (Brave, Bing, Google, Tavily, SearXNG, DuckDuckGo, and more) for real-time information +- **Web Fetch** — Retrieve and parse web page content - **Browser Automation** — Use Playwright-powered browser tools for navigation, clicking, form filling, screenshots, PDF export, and rendered page inspection -- **Subagents** — Create specialized subagents with independent context, assign skills, and delegate complex tasks +- **Subagents** — Create specialized subagents with independent context, assign skills, and delegate complex tasks in parallel - **Skills** — Define bot personality via IDENTITY.md, SOUL.md, and modular skill files that bots can enable/disable at runtime - **Container Operations** — Read/write files, edit code, and execute commands inside the container - **Memory Management** — Search and manage memories -- **Text-to-Speech** — Synthesize speech via configurable TTS providers (Edge TTS with 256+ voices) - **Messaging** — Send messages and reactions to specific users or channels +- **Email** — Compose and send emails through configured email providers +- **Text-to-Speech** — Synthesize spoken audio from text using configurable TTS providers +- **MCP Federation** — Access external tools and resources via federated MCP connections +- **Session History** — Access and manage conversation session history + +### Sessions + +Each bot maintains **sessions** — independent conversation threads that preserve context. Sessions come in four types: + +- **Chat** — Standard user conversations +- **Heartbeat** — Periodic autonomous activity sessions +- **Schedule** — Cron-triggered task execution sessions +- **Subagent** — Delegated task sessions for sub-agents + +Users can start a new session at any time using the `/new` slash command in any channel, which resets the conversation context. + +### Slash Commands + +Bots support a comprehensive set of slash commands that can be used directly in any channel: + +- `/help` — Show available commands +- `/new` — Start a new conversation session +- `/schedule` — Manage scheduled tasks +- `/settings` — View and update bot settings +- `/model` — Switch chat or heartbeat models +- `/usage` — View token usage statistics +- And more — see [Slash Commands](/getting-started/slash-commands) for the full reference. ### Multi-LLM Provider Support @@ -59,19 +89,19 @@ Flexibly switch between a wide range of LLM providers via four client types: - OpenAI Responses API, OpenAI Chat Completions API (including compatible services) - Anthropic Messages API, Google Generative AI API -Per-bot model assignment for chat, memory, and embedding. +Per-bot model assignment for chat, memory, and embedding. Providers support OAuth authentication and automatic model import. ### MCP Protocol Support -Full MCP (Model Context Protocol) support via HTTP, SSE, and Stdio to connect external tool services. Built-in tools for container operations, memory search, web search, scheduling, messaging, and more. Each bot can have its own independent MCP connections. +Full MCP (Model Context Protocol) support via HTTP, SSE, and Stdio to connect external tool services. Built-in tools for container operations, memory search, web search, scheduling, messaging, and more. Each bot can have its own independent MCP connections with OAuth authentication support. ### Scheduled Tasks Configure scheduled tasks using cron expressions to automatically run commands at specified times. Supports max execution count limits and manual triggers. -### Inbox +### Memory Compaction -Cross-channel inbox — messages from other channels are queued and surfaced in the system prompt so the bot never misses context. +Automatic memory compaction reduces redundancy in the bot's memory pool over time. Configurable compaction ratios and decay windows keep the most relevant memories while optimizing storage and retrieval quality. ### Graphical Configuration @@ -81,4 +111,4 @@ Modern web UI (Vue 3 + Tailwind CSS) with real-time streaming chat, tool call vi To get Memoh running: -- **[Docker](/installation/docker)** — Recommended. One-click or manual setup with Docker Compose. Includes all services (PostgreSQL, Qdrant, Containerd, server, agent, web) — no extra dependencies on the host. +- **[Docker](/installation/docker)** — Recommended. One-click or manual setup with Docker Compose. Includes all services (PostgreSQL, Qdrant, Containerd, server, web) — no extra dependencies on the host. diff --git a/docs/docs/channels/discord.md b/docs/docs/channels/discord.md index bb2c5eb4..37bc3908 100644 --- a/docs/docs/channels/discord.md +++ b/docs/docs/channels/discord.md @@ -27,7 +27,7 @@ Connecting your Memoh Bot to Discord allows it to join servers and interact with ## Step 4: Configure Memoh -1. Go to your Bot's **Channels** tab in the Memoh Web UI. +1. Go to your Bot's **Platforms** tab in the Memoh Web UI. 2. Click **Add Channel** and select **Discord**. 3. Paste your **Bot Token**. 4. Click **Save and Enable**. diff --git a/docs/docs/channels/feishu.md b/docs/docs/channels/feishu.md index eb872559..19d21c22 100644 --- a/docs/docs/channels/feishu.md +++ b/docs/docs/channels/feishu.md @@ -25,7 +25,7 @@ Memoh supports integrating with Feishu (Lark) via the Open Platform. This allows ## Step 4: Configure Events (Webhook Mode) -1. In Memoh, go to your Bot's **Channels** tab and add a **Feishu** channel. +1. In Memoh, go to your Bot's **Platforms** tab and add a **Feishu** channel. 2. Choose **Inbound Mode**: `webhook`. 3. Fill in your **App ID** and **App Secret**. 4. Click **Save**. Memoh will generate a **Webhook Callback URL**. diff --git a/docs/docs/channels/index.md b/docs/docs/channels/index.md index 09cfcbef..dc285055 100644 --- a/docs/docs/channels/index.md +++ b/docs/docs/channels/index.md @@ -4,18 +4,21 @@ Channels are the gateways that connect your Memoh Bots to the outside world. By Memoh currently supports the following channels: -- **[Telegram](./telegram)**: The most feature-rich integration with streaming and attachment support. +- **[Telegram](./telegram)**: Feature-rich integration with streaming and attachment support. - **[Feishu (Lark)](./feishu)**: Enterprise-ready integration for business workflows. - **[Discord](./discord)**: Community-focused integration for servers and direct messages. - **[QQ](./qq)**: Quick setup for personal DM bots via the dedicated AI bot registration portal. -- **Email**: Connect via standard SMTP and IMAP (configured through Email Providers). +- **[Matrix](./matrix)**: Decentralized messaging protocol support for any Matrix homeserver. +- **[WeCom (WeWork)](./wecom)**: Enterprise messaging integration for WeCom workspaces. +- **[WeChat](./weixin)**: Personal messaging via the WeChat AI bot platform. +- **Email**: Connect via SMTP providers, Mailgun, or Gmail OAuth (configured through Email Providers). - **Web**: Built-in chat interface for immediate access. ## General Setup Flow 1. **Create an external app/bot**: Register your bot on the target platform (e.g., via BotFather on Telegram). 2. **Obtain credentials**: Fetch API tokens, App IDs, or secrets. -3. **Configure in Memoh**: Add the channel to your Bot's settings and paste the credentials. +3. **Configure in Memoh**: Add the channel to your Bot's **Platforms** tab and paste the credentials. 4. **Enable**: Activate the channel to start receiving and sending messages. Choose a channel from the sidebar to see detailed configuration guides for each platform. diff --git a/docs/docs/channels/matrix.md b/docs/docs/channels/matrix.md new file mode 100644 index 00000000..8090c073 --- /dev/null +++ b/docs/docs/channels/matrix.md @@ -0,0 +1,48 @@ +# Matrix Channel Configuration + +Connecting your Memoh Bot to Matrix allows it to communicate via the decentralized Matrix messaging protocol. Your bot can join rooms, respond to direct messages, and participate in group conversations on any Matrix homeserver. + +## Step 1: Create a Matrix Bot Account + +1. Register a new account on your Matrix homeserver (e.g., via Element or any Matrix client). +2. Note the **User ID** (e.g., `@mybot:matrix.org`). +3. Obtain an **Access Token** for the account. You can do this by: + - Using the Matrix client login API: `POST /_matrix/client/r0/login` + - Or extracting it from your Matrix client's settings (Element: Settings > Help & About > Access Token). + +> **Important**: Keep the access token secret. Anyone with this token can act as your bot account. + +## Step 2: Configure Memoh + +1. Go to your Bot's **Platforms** tab in the Memoh Web UI. +2. Click **Add Channel** and select **Matrix**. +3. Fill in the required fields: + +| Field | Required | Description | +|-------|----------|-------------| +| **Homeserver URL** | Yes | The base URL of your Matrix homeserver (e.g., `https://matrix.org`). | +| **Access Token** | Yes | The bot account's access token. | +| **User ID** | Yes | The bot's Matrix user ID (e.g., `@mybot:matrix.org`). | +| **Sync Timeout** | No | Long-polling timeout in seconds (default: 30). | +| **Auto Join Invites** | No | Automatically join rooms when invited (default: enabled). | + +4. Click **Save and Enable**. + +## Step 3: Invite the Bot + +1. Open your Matrix client (Element, etc.). +2. Invite the bot's user ID to a room, or start a direct message. +3. If **Auto Join Invites** is enabled, the bot will automatically accept and join. + +## Features Supported + +- **Message Content**: Full access to text messages. +- **Rooms**: Join and participate in group rooms. +- **Direct Messages**: Private conversations with individual users. +- **Streaming**: Responses are streamed as they are generated. +- **Markdown**: Support for formatted text. + +## Official Resources + +- [Matrix Specification](https://spec.matrix.org/) +- [Element Web Client](https://app.element.io/) diff --git a/docs/docs/channels/qq.md b/docs/docs/channels/qq.md index 70ae2175..513e87bf 100644 --- a/docs/docs/channels/qq.md +++ b/docs/docs/channels/qq.md @@ -12,7 +12,7 @@ Connecting your Memoh Bot to QQ allows it to interact with users through QQ's of ## Step 2: Configure Memoh -1. Go to your Bot's **Channels** tab in the Memoh Web UI. +1. Go to your Bot's **Platforms** tab in the Memoh Web UI. 2. Click **Add Channel** and select **QQ**. 3. Paste your **AppID** and **AppSecret**. 4. Configure optional settings: @@ -22,9 +22,9 @@ Connecting your Memoh Bot to QQ allows it to interact with users through QQ's of ## Step 3: Bind Your Identity (Optional) -If your bot is a `personal` type bot, bind your QQ identity to chat with it directly: +Binding your QQ identity to your Memoh account enables cross-platform identity recognition — the bot will know who you are regardless of which channel you use. -1. In Memoh Web UI, go to **Settings** > **Bind Code**. +1. In Memoh Web UI, go to **Profile** > **Bind Code**. 2. Select **QQ** and click **Generate**. 3. Copy the code and send it to your bot in a QQ direct message. diff --git a/docs/docs/channels/telegram.md b/docs/docs/channels/telegram.md index ffa99b2e..ee5b5d62 100644 --- a/docs/docs/channels/telegram.md +++ b/docs/docs/channels/telegram.md @@ -18,16 +18,16 @@ You need to create a bot on Telegram to get an API token. ## Step 2: Configure Memoh 1. Go to your Bot's **Detail Page** in the Memoh Web UI. -2. Select the **Channels** tab. +2. Select the **Platforms** tab. 3. Click **Add Channel** and select **Telegram**. 4. Paste your **API Token** into the credentials field. 5. Click **Save and Enable**. ## Step 3: Bind Your Identity (Optional) -If your bot is a `personal` type bot, you need to bind your Telegram identity to your Memoh account to chat with it directly. +Binding your Telegram identity to your Memoh account enables cross-platform identity recognition — the bot will know who you are regardless of which channel you use. -1. In Memoh Web UI, go to **Settings** > **Bind Code**. +1. In Memoh Web UI, go to **Profile** > **Bind Code**. 2. Select **Telegram** and click **Generate**. 3. Copy the code. 4. Open a chat with your new bot on Telegram and send the bind code. diff --git a/docs/docs/channels/wecom.md b/docs/docs/channels/wecom.md new file mode 100644 index 00000000..d59cef7b --- /dev/null +++ b/docs/docs/channels/wecom.md @@ -0,0 +1,40 @@ +# WeCom (WeWork) Channel Configuration + +Connecting your Memoh Bot to WeCom (企业微信) allows it to interact with users within your organization's WeCom workspace. + +## Step 1: Create a WeCom Bot + +1. Log in to the [WeCom Admin Console](https://work.weixin.qq.com/). +2. Navigate to **App Management** > **Custom Apps** or **Bot Management**. +3. Create a new bot application. +4. Note the **Bot ID** and **Secret** credentials. + +## Step 2: Configure Memoh + +1. Go to your Bot's **Platforms** tab in the Memoh Web UI. +2. Click **Add Channel** and select **WeCom**. +3. Fill in the required fields: + +| Field | Required | Description | +|-------|----------|-------------| +| **Bot ID** | Yes | The WeCom bot identifier. | +| **Secret** | Yes | The bot's authentication credential. | +| **WebSocket URL** | No | Custom WebSocket endpoint (uses default if empty). | + +4. Click **Save and Enable**. + +## Step 3: Start Chatting + +Once the channel is enabled, the bot will connect to WeCom via WebSocket and begin receiving messages. Users in your WeCom workspace can send messages to the bot directly or in group chats. + +## Features Supported + +- **Message Content**: Full support for text messages. +- **Direct Messages**: Private conversations with individual users. +- **Group Chats**: Participate in group conversations. +- **Streaming**: Responses are streamed in real-time. + +## Official Resources + +- [WeCom Open Platform](https://developer.work.weixin.qq.com/) +- [WeCom Bot Documentation](https://developer.work.weixin.qq.com/document/path/91770) diff --git a/docs/docs/channels/weixin.md b/docs/docs/channels/weixin.md new file mode 100644 index 00000000..d429919a --- /dev/null +++ b/docs/docs/channels/weixin.md @@ -0,0 +1,34 @@ +# WeChat Channel Configuration + +Connecting your Memoh Bot to WeChat allows it to interact with users directly via WeChat personal messaging. Setup is simple — just scan a QR code. + +## Step 1: Add WeChat Channel in Memoh + +1. Go to your Bot's **Platforms** tab in the Memoh Web UI. +2. Click **Add Channel** and select **WeChat**. + +## Step 2: Scan the QR Code + +1. Click **Start QR Login**. Memoh will fetch a QR code from the WeChat platform. +2. Open WeChat on your phone and scan the displayed QR code. +3. Confirm the login on your phone when prompted. +4. Once confirmed, Memoh automatically saves the credentials — no manual token or API key entry is needed. + +The QR code has a limited validity window. If it expires before you scan, click **Start QR Login** again to get a fresh one. + +## Step 3: Start Chatting + +After the QR login succeeds, the channel is automatically enabled. Users can now send messages to the bot directly in WeChat. + +## Optional Settings + +| Field | Description | +|-------|-------------| +| **Enable Typing** | Show typing indicators while generating responses. | + +## Features Supported + +- **Message Content**: Full support for text messages. +- **Direct Messages**: Private conversations with individual users. +- **Attachments**: Support for images and media. +- **Typing Indicators**: Visual feedback while generating responses (when enabled). diff --git a/docs/docs/getting-started/access.md b/docs/docs/getting-started/access.md index 9348fb5f..ab33adf1 100644 --- a/docs/docs/getting-started/access.md +++ b/docs/docs/getting-started/access.md @@ -1,17 +1,17 @@ # Bot Access Control -Memoh uses an ACL (Access Control List) system to control who can interact with your bot. You can configure guest access, whitelist specific users or channel identities, and blacklist others — all from the bot's **Access** tab. +Memoh uses an ACL (Access Control List) system to control who can interact with your bot. You can define prioritized rules to allow or deny specific users, channel identities, or entire channel types — all from the bot's **Access** tab. --- ## Concepts -### Authorization Layers +### Default Effect -Bot access is enforced at two levels: +Each bot has a **default effect** (`allow` or `deny`) that applies when no ACL rule matches an incoming message. Configure this in the bot's **General** tab under **ACL Default Effect**. -1. **Management Access**: Only the bot **owner** and system **admins** can edit bot settings, manage ACL rules, and configure the bot. This is not configurable — it is based on ownership. -2. **Chat Trigger Access**: Controls who can send messages to the bot and trigger a response. This is what the ACL system manages. +- **Allow**: Anyone can chat with the bot unless explicitly denied by a rule. +- **Deny**: Only the bot owner, admins, and explicitly allowed subjects can chat. ### Subject Types @@ -19,21 +19,27 @@ ACL rules can target three kinds of subjects: | Subject | Description | |---------|-------------| -| **Guest (all)** | A global toggle — when enabled, anyone can chat with the bot without being explicitly listed. | -| **User** | A specific Memoh user account. | -| **Channel Identity** | A specific identity on an external channel (e.g. a Telegram user, a Discord member). Useful when the person doesn't have a Memoh account. | +| **All** | Matches every incoming message regardless of sender. Use this for global allow/deny rules. | +| **Channel Identity** | A specific identity on an external channel (e.g., a Telegram user, a Discord member). Useful for controlling access at the individual level. | +| **Channel Type** | An entire channel platform (e.g., all Telegram users, all Discord users). Useful for platform-level access control. | -### Evaluation Order +### Rule Effects -When an incoming message arrives, the bot evaluates access in this order: +Each rule has an **effect**: -1. Bot owner or system admin → **Allow** -2. User or channel identity has a **deny** rule → **Deny** -3. User or channel identity has an **allow** rule → **Allow** -4. Guest access is enabled → **Allow** -5. None of the above → **Deny** +- **Allow** — Grants the subject permission to chat with the bot. +- **Deny** — Blocks the subject from chatting with the bot. -Blacklist (deny) rules are always checked before whitelist (allow) rules. This means a blacklisted user cannot bypass the block even if guest access is enabled. +### Priority-Based Evaluation + +Rules are evaluated in **priority order** (top to bottom). The first matching rule determines the outcome: + +1. Bot owner or system admin → **Always allowed** (bypasses ACL). +2. Rules are checked from highest priority (top) to lowest (bottom). +3. The first rule whose subject matches the sender is applied. +4. If no rule matches → the **default effect** is applied. + +This means rule ordering matters. A deny rule placed above an allow rule will take precedence for matching subjects. --- @@ -41,69 +47,64 @@ Blacklist (deny) rules are always checked before whitelist (allow) rules. This m Open a bot's **Access** tab to configure its access control. -### Guest Access +### Adding Rules -Toggle **Allow Guest Access** to let anyone chat with the bot without an explicit whitelist entry. This is useful for public-facing bots. - -When guest access is disabled, only the bot owner, admins, and explicitly whitelisted users/identities can trigger the bot. - -### Whitelist - -The whitelist grants specific users or channel identities permission to chat with the bot. - -1. Click **Add** in the Whitelist section. +1. Click **Add Rule**. 2. Select a subject type: - - **User**: Search and select a Memoh user. - - **Channel Identity**: Search and select a channel identity (e.g. a Telegram user the bot has seen before). -3. Optionally set **source scope** to restrict the rule to a specific context: - - **Channel**: Only applies when the message comes from a specific channel (e.g. your Telegram bot channel). + - **All**: Applies to everyone. + - **Channel Identity**: Search and select a specific channel identity the bot has seen before. + - **Channel Type**: Select an entire channel platform. +3. Choose the **effect**: `allow` or `deny`. +4. Optionally set **source scope** to restrict the rule to a specific context: + - **Channel**: Only applies when the message comes from a specific channel config. - **Conversation Type**: `private`, `group`, or `thread`. - **Conversation ID**: A specific chat/group ID. - **Thread ID**: A specific thread within a conversation (requires Conversation ID). -4. Click **Save**. +5. Click **Save**. -Without source scope, the rule applies globally — the subject can chat with the bot from any channel. +### Reordering Rules -### Blacklist - -The blacklist denies specific users or channel identities from chatting with the bot. The setup process is the same as the whitelist. - -Blacklist rules take priority over whitelist rules and guest access. Use this to block specific users while keeping the bot open to others. +Rules can be **drag-and-dropped** to change their priority. Higher rules (closer to the top) are evaluated first. After reordering, click **Save** to persist the new order. ### Source Scope Source scope lets you create fine-grained rules. For example: -- Allow a user to chat only via Telegram, but not Discord -- Block a channel identity only in group conversations -- Restrict access to a specific thread in a specific group +- Allow a user to chat only via Telegram, but not Discord. +- Block an entire channel type only in group conversations. +- Restrict access to a specific thread in a specific group. -Scope fields form a hierarchy: **Channel → Conversation Type → Conversation ID → Thread ID**. Each level is optional, but a Thread ID requires a Conversation ID, and a Conversation ID requires a Channel. +Scope fields form a hierarchy: **Channel → Conversation Type → Conversation ID → Thread ID**. Each level is optional, but a Thread ID requires a Conversation ID. --- ## Examples -### Public Bot (Anyone Can Chat) +### Open Bot (Anyone Can Chat) -1. Open the bot's **Access** tab. -2. Enable **Allow Guest Access**. -3. Done — anyone on any connected channel can now message the bot. +1. Set **ACL Default Effect** to `allow` in the **General** tab. +2. No rules needed — everyone is allowed by default. ### Private Bot with Selected Users -1. Disable **Allow Guest Access**. -2. Add each authorized user or channel identity to the **Whitelist**. +1. Set **ACL Default Effect** to `deny`. +2. Add **allow** rules for each authorized channel identity. 3. Only listed subjects (plus the bot owner and admins) can trigger the bot. -### Public Bot with Blocked Users +### Open Bot with Blocked Users -1. Enable **Allow Guest Access**. -2. Add problematic users/identities to the **Blacklist**. -3. Everyone except blacklisted subjects can chat with the bot. +1. Set **ACL Default Effect** to `allow`. +2. Add **deny** rules for problematic channel identities at the top of the list. +3. Everyone except denied subjects can chat with the bot. + +### Platform-Specific Access + +1. Set **ACL Default Effect** to `deny`. +2. Add an **allow** rule with subject type **Channel Type** set to `telegram`. +3. Only Telegram users can chat with the bot — messages from other channels are denied. ### Channel-Scoped Access -1. Add a whitelist rule for a user. -2. Set the **Channel** source scope to your Telegram channel. -3. The user can only chat with the bot via Telegram — messages from other channels are denied. +1. Add an **allow** rule for a specific channel identity. +2. Set the **Source Scope** channel to your Telegram channel config. +3. The user can only chat with the bot via that specific Telegram channel. diff --git a/docs/docs/getting-started/bot.md b/docs/docs/getting-started/bot.md index 0aad58b6..6687679d 100644 --- a/docs/docs/getting-started/bot.md +++ b/docs/docs/getting-started/bot.md @@ -7,33 +7,43 @@ A Bot is an independent AI agent that comes with its own isolated container, per 1. Navigate to the **Bots** page from the sidebar. 2. Click the **Create Bot** button. 3. Fill in the basic info: - - **Display Name**: The name users will see in group chats. + - **Display Name**: The name users will see in chats. - **Avatar**: A URL for the bot's profile picture. - - **Type**: Choose `personal` (private to owner) or `public` (accessible to guests). 4. Click **Create**. --- ## Bot Detail Page -Once created, clicking on a bot card takes you to its **Detail Page**, where you can manage its entire lifecycle through several specialized tabs. +Once created, clicking on a bot card takes you to its **Detail Page**, where you can manage its entire lifecycle through specialized tabs. -### Overview Tab +### Tab Overview -The **Overview** tab provides a quick health check of the bot's services. It monitors: -- Container status (running/stopped) -- Database connectivity -- Channel configurations -- Memory system health +| Tab | Description | +|-----|-------------| +| **Overview** | Health checks for container, database, channels, and memory. | +| **General** | Core settings: models, providers, reasoning, heartbeat, compaction, and danger zone. | +| **Container** | Container lifecycle (create/start/stop), snapshots, data export/import. | +| **Memory** | Browse, search, create, edit, and compact memories. | +| **Platforms** | Channel configurations (Telegram, Discord, Feishu, QQ, Matrix, WeCom, WeChat, Web). | +| **Access** | ACL rules — control who can chat with the bot. | +| **Email** | Email bindings and outbox. | +| **Terminal** | Interactive terminal access to the bot's container. | +| **Files** | File manager for the bot's container filesystem. | +| **MCP** | MCP connection management (Stdio, Remote, OAuth). | +| **Heartbeat** | Heartbeat configuration and execution logs. | +| **Compaction** | Memory compaction logs. | +| **Schedule** | Cron-based scheduled tasks and execution logs. | +| **Skills** | Markdown-based skill files that define bot personality and capabilities. | -If any check shows a warning or error, follow the provided details to troubleshoot. +--- ## Configuring the Bot's Core Settings After creating a bot, the most important step is configuring its runtime settings. These define how the bot talks, remembers, searches, and uses browser automation. 1. Navigate to your bot's **Detail Page**. -2. Go to the **Settings** tab. +2. Go to the **General** tab. 3. Configure the core fields: - **Chat Model**: Used for standard conversations with users. - **Memory Provider**: Select the memory backend the bot should use. @@ -50,9 +60,9 @@ If you have not created these resources yet, set them up first: --- -## Settings Tab Reference +## General Tab Reference -The **Settings** tab contains all the core parameters that define your bot's behavior and runtime configuration. +The **General** tab contains all the core parameters that define your bot's behavior and runtime configuration. | Field | Description | |-------|-------------| @@ -60,19 +70,32 @@ The **Settings** tab contains all the core parameters that define your bot's beh | **Memory Provider** | The memory backend assigned to the bot. The built-in provider can optionally define its own memory and embedding models. | | **Search Provider** | The search engine used for web browsing capabilities. | | **Browser Context** | The browser environment used for web automation, such as viewport, locale, and mobile behavior. | -| **Max Context Load Time** | Time limit (seconds) for loading context before generation. | -| **Max Context Tokens** | Token limit for the loaded conversation history. | | **Language** | The bot's primary communication language. | | **Reasoning Enabled** | If the selected model supports reasoning (like OpenAI o1), enable this to use its deep thinking capabilities. | | **Reasoning Effort** | Set the level of reasoning effort (`low`, `medium`, `high`). | -| **Allow Guest** | (Public bots only) If enabled, non-registered users can interact with the bot. | +| **Heartbeat Enabled** | Toggle periodic autonomous activity. | +| **Heartbeat Interval** | How often (in minutes) the heartbeat triggers. | +| **Heartbeat Model** | The LLM used for heartbeat tasks (can differ from the chat model). | +| **Compaction Enabled** | Toggle automatic memory compaction. | +| **Compaction Model** | The LLM used for memory compaction. | +| **ACL Default Effect** | Default access control behavior (`allow` or `deny`) when no ACL rule matches. | + +--- + +## Terminal Tab + +The **Terminal** tab provides interactive shell access to the bot's container: + +- Open multiple terminal tabs simultaneously. +- Execute commands directly inside the container. +- Requires the container to be running. --- ## Deleting a Bot To permanently remove a bot and all its associated data (including container files and memory): -1. Navigate to the **Settings** tab in the Bot Detail page. +1. Navigate to the **General** tab in the Bot Detail page. 2. Scroll to the **Danger Zone** at the bottom. 3. Click **Delete Bot** and confirm the action. diff --git a/docs/docs/getting-started/browser.md b/docs/docs/getting-started/browser.md index 36363c73..24c0b01f 100644 --- a/docs/docs/getting-started/browser.md +++ b/docs/docs/getting-started/browser.md @@ -59,7 +59,7 @@ After creating a context, select it from the sidebar and update its settings. ## Assigning a Browser Context to a Bot 1. Navigate to the **Bots** page and open your bot. -2. Go to the **Settings** tab. +2. Go to the **General** tab. 3. Find the **Browser Context** dropdown. 4. Select the context you created. 5. Click **Save**. diff --git a/docs/docs/getting-started/channels.md b/docs/docs/getting-started/channels.md index d27c1b56..e4290d97 100644 --- a/docs/docs/getting-started/channels.md +++ b/docs/docs/getting-started/channels.md @@ -4,15 +4,15 @@ Channels connect your Bot to various messaging platforms, allowing you to intera ## Concept: Unified Communication -Memoh acts as a hub that bridges different messaging services. You can configure multiple channels for a single bot, enabling it to chat on Telegram, Discord, and more simultaneously. +Memoh acts as a hub that bridges different messaging services. You can configure multiple channels for a single bot, enabling it to chat on Telegram, Discord, Matrix, and more simultaneously. --- ## Supported Channels -Configure your bot's connections from the **Channels** tab in the Bot Detail page. +Configure your bot's connections from the **Platforms** tab in the Bot Detail page. -### Popular Platforms +### Platform Guides For detailed step-by-step guides on how to create and configure bots for each platform, see: @@ -20,6 +20,9 @@ For detailed step-by-step guides on how to create and configure bots for each pl - **[Feishu (Lark) Configuration](/channels/feishu)** - **[Discord Configuration](/channels/discord)** - **[QQ Configuration](/channels/qq)** +- **[Matrix Configuration](/channels/matrix)** +- **[WeCom (WeWork) Configuration](/channels/wecom)** +- **[WeChat Configuration](/channels/weixin)** --- @@ -46,6 +49,12 @@ If using **Feishu** in `webhook` inbound mode: 2. Copy this URL and paste it into your Feishu App's event configuration. 3. This allows Feishu to send messages directly to Memoh. +### 4. Special Case: WeChat QR Code + +If using **WeChat**: +1. After enabling the channel, a QR code flow is provided for connecting. +2. Scan the QR code with WeChat to link the bot. + --- ## Operations diff --git a/docs/docs/getting-started/compaction.md b/docs/docs/getting-started/compaction.md new file mode 100644 index 00000000..3b9a4a8a --- /dev/null +++ b/docs/docs/getting-started/compaction.md @@ -0,0 +1,75 @@ +# Memory Compaction + +As a bot accumulates memories over time, the memory pool can grow large and contain redundant or outdated entries. **Memory Compaction** is an automated process that consolidates and optimizes the bot's memory store, keeping the most relevant information while reducing noise. + +--- + +## Concept: Why Compact? + +Each conversation turn can generate new memory entries. Over weeks or months of use, thousands of memories accumulate. Many of these may overlap, become stale, or lose relevance. Compaction addresses this by: + +- **Merging redundant memories** — Combining entries that express the same information. +- **Removing outdated entries** — Discarding memories that are no longer accurate. +- **Reducing retrieval noise** — Fewer, higher-quality memories lead to better search results during chat. + +--- + +## Configuration + +Configure compaction from the **General** tab in the Bot Detail page. + +| Field | Description | +|-------|-------------| +| **Compaction Enabled** | Toggle automatic memory compaction on or off. | +| **Compaction Model** | The LLM used to evaluate and merge memories during compaction. This can be different from the chat model. | + +When enabled, compaction runs periodically as part of the bot's memory maintenance cycle. + +--- + +## Manual Compaction + +You can also trigger compaction manually from the bot's **Memory** tab: + +1. Navigate to the **Memory** tab in the Bot Detail page. +2. Click **Compact**. +3. Configure the compaction parameters: + - **Ratio** — The compression ratio (e.g., `0.8`, `0.5`, `0.3`). Lower values mean more aggressive compaction. + - **Decay Days** — Optionally restrict compaction to memories older than a specified number of days. +4. Click **Start Compaction**. + +--- + +## Compaction Logs + +The **Compaction** tab in the Bot Detail page provides an audit trail of all compaction runs: + +- **Status** — Whether the compaction completed successfully, encountered an issue, or failed. +- **Time** — When the compaction was triggered. +- **Duration** — How long the compaction took. +- **Result** — A summary of what was compacted (memories merged, removed, etc.). + +### Managing Logs + +- **Refresh** — Reload the log list. +- **Clear Logs** — Remove old compaction records. + +--- + +## Relationship to Memory + +Compaction works with whatever **Memory Provider** is assigned to the bot. The compaction process: + +1. Reads all existing memories from the provider. +2. Uses the configured **Compaction Model** to evaluate which memories are redundant or stale. +3. Merges, updates, or removes entries as needed. +4. Writes the optimized memory set back to the provider. + +This process preserves the semantic content of important memories while reducing the total count. After compaction, the bot's memory retrieval becomes faster and more focused. + +--- + +## Next Steps + +- To manage individual memories, see [Memory Management](/getting-started/memory). +- To configure the memory backend, see [Memory Providers](/memory-providers/index). diff --git a/docs/docs/getting-started/container.md b/docs/docs/getting-started/container.md index 6cb3ad75..3e20b67d 100644 --- a/docs/docs/getting-started/container.md +++ b/docs/docs/getting-started/container.md @@ -18,10 +18,10 @@ Manage the lifecycle of your bot's environment from the **Container** tab in the ### Lifecycle Actions -- **Create**: Initialize the container if it doesn't exist (using the configured image). +- **Create**: Initialize the container if it doesn't exist (using the configured image). Progress is shown via real-time SSE feedback during image pull and creation. - **Start**: Launch the container. The bot must have a running container to perform many operations like file editing or executing tools. - **Stop**: Gracefully shut down the container to save resources. -- **Delete**: Remove the container instance. This will delete the temporary state but preserve the data in persistent volumes. +- **Delete**: Remove the container instance. --- @@ -54,3 +54,36 @@ Snapshots allow you to capture the current state of the bot's container and rest ### Managing Snapshots - View a list of existing snapshots with their creation timestamps and parent relationships. - Use the **Delete** button next to a snapshot to remove it. + +--- + +## Data Export and Import + +The Container tab supports exporting and importing container data for backup, migration, or sharing purposes. + +### Export + +1. Click **Export Data**. +2. The container's filesystem data is packaged into a downloadable archive. +3. Save the archive to your local machine. + +### Import + +1. Click **Import Data**. +2. Select an archive file from your local machine. +3. The archive contents are extracted into the container's filesystem. + +### Restore + +The **Restore** operation resets the container's data directory to a clean state. This is useful when the filesystem has become corrupted or you want to start fresh without recreating the container. + +--- + +## Container Versioning + +Memoh tracks container versions to manage the lifecycle of the bot's runtime environment. Version information includes: + +- **Current Version**: The active container version. +- **Version History**: A log of container version changes over time. + +This helps with auditing and understanding when container configurations were updated. diff --git a/docs/docs/getting-started/mcp.md b/docs/docs/getting-started/mcp.md index bbecf441..e751c4c8 100644 --- a/docs/docs/getting-started/mcp.md +++ b/docs/docs/getting-started/mcp.md @@ -14,7 +14,7 @@ Configure MCP connections from the **MCP** tab in the Bot Detail page. ### 1. Stdio (Local Process) -This type of connection executes a local command on the server and communicates via standard input/output. +This type of connection executes a local command inside the bot's container and communicates via standard input/output. | Field | Description | |-------|-------------| @@ -35,13 +35,43 @@ This type of connection connects to a remote MCP server over the network. --- +## OAuth Authentication + +Some MCP servers require OAuth-based authentication. Memoh supports the full MCP OAuth flow: + +1. Click the **OAuth** button on a connection that requires authentication. +2. Memoh will **discover** the server's OAuth configuration automatically. +3. Click **Authorize** to open the provider's authorization page. +4. After granting access, you are redirected back to Memoh. +5. The token is **exchanged** and stored securely for the connection. + +You can also: + +- **Check status** — View the current OAuth token status. +- **Revoke** — Remove the stored OAuth token. + +--- + ## Operations - **Add Connection**: Click **Add**, choose the type, and fill in the configuration. - **Import JSON**: Use the **Import** button to quickly add multiple connections from a standard `mcpServers` JSON config file. +- **Export**: Export connection configurations to a JSON file for backup or sharing. - **Toggle Active**: Enable or disable specific connections without deleting them. - **Search**: Quickly find a connection by name or ID. -- **Export**: Export a connection configuration to a JSON file. +- **Batch Delete**: Select multiple connections and delete them at once. + +--- + +## Tool Discovery + +Once an MCP connection is active, Memoh automatically discovers the tools exposed by the server. You can: + +1. Click on a connection to view its details. +2. The **Tools** section lists all available tools with their names and descriptions. +3. The bot will use these tools automatically during conversations when relevant. + +You can also use the **Probe** button to manually refresh the tool list from the server. --- diff --git a/docs/docs/getting-started/memory.md b/docs/docs/getting-started/memory.md index d68ff4c7..7c068091 100644 --- a/docs/docs/getting-started/memory.md +++ b/docs/docs/getting-started/memory.md @@ -7,7 +7,7 @@ Memoh's structured long-term memory system allows bots to remember information a Before using the **Memory** tab, make sure your bot already has a **Memory Provider** configured. 1. Create a provider from one of the [Memory Providers](/memory-providers/index.md) (Built-in, Mem0, or OpenViking). -2. Open your bot's **Settings** tab. +2. Open your bot's **General** tab. 3. Select the provider in the **Memory Provider** field. 4. Click **Save**. @@ -45,17 +45,39 @@ Over time, memories can accumulate and become redundant. The **Compact** feature - **Ratio**: Set the compression ratio (for example `0.8`, `0.5`, or `0.3`) to determine how much information is retained. - **Decay Days**: Optionally specify a time window to compact only memories older than a certain number of days. +For more details on compaction, see [Memory Compaction](/getting-started/compaction). + --- -## Visualization: Vector Manifold +## Rebuild -The Memory tab includes visual tools to help you understand how the memory system is performing: +The **Rebuild** feature re-indexes all memories from scratch. This is useful when: -### Top-K Bucket Chart -Shows the distribution of relevant memories retrieved for the most recent queries. +- You have changed the memory provider's mode (e.g., switching from `off` to `sparse`). +- The vector index has become inconsistent. +- You want to re-process all memories with updated settings. -### CDF Curve (Cumulative Distribution Function) -Visualizes the scoring threshold of retrieved memories, helping you fine-tune how much relevant information the bot should consider. +Click **Rebuild** in the Memory tab to start the process. You can monitor the rebuild status in real-time. + +--- + +## Status + +The Memory tab shows the current **status** of the memory provider for this bot: + +- **Connected** — The memory backend is reachable and operational. +- **Error** — There is an issue with the memory provider configuration or connectivity. + +Use the status indicator to quickly verify that the memory system is working before troubleshooting other issues. + +--- + +## Usage Statistics + +The Memory tab displays storage usage information: + +- **Total Memories** — The number of memory entries stored for this bot. +- **Index Status** — Whether the vector index is up-to-date. --- diff --git a/docs/docs/getting-started/provider-and-model.md b/docs/docs/getting-started/provider-and-model.md index bcd8ac69..b3e169a8 100644 --- a/docs/docs/getting-started/provider-and-model.md +++ b/docs/docs/getting-started/provider-and-model.md @@ -8,7 +8,7 @@ An LLM Provider represents a connection to an AI service (like OpenAI, Anthropic ### Creating a Provider -1. Navigate to the **Models** page from the sidebar. +1. Navigate to the **Providers** page from the sidebar. 2. Click the **Add Provider** button at the bottom of the sidebar. 3. Fill in the following fields: - **Name**: A display name for this provider (e.g., "OpenAI"). @@ -16,9 +16,30 @@ An LLM Provider represents a connection to an AI service (like OpenAI, Anthropic - **API Key**: Your authentication token for the service. 4. Click **Create**. +### OAuth Authentication + +Some providers (like OpenAI) support OAuth-based authentication. If a provider supports OAuth: + +1. Select the provider from the list. +2. Click **Connect with OAuth** in the provider settings form. +3. Follow the authorization flow in the popup window. +4. Once authorized, the provider will use the OAuth token instead of a manual API key. + +### Import Models + +Memoh can automatically discover and import available models from a provider: + +1. Select a provider from the list. +2. Click **Import Models**. +3. Memoh will query the provider's API to fetch available models. +4. Select which models to import and click **Import**. + +This saves time compared to manually adding each model one by one. + ### Managing Providers - **Edit**: Select a provider from the list and use the form on the right to update its name, URL, or API key. +- **Test**: Click **Test Connection** to verify the provider is reachable. - **Delete**: Use the **Delete Provider** button in the provider settings form. --- @@ -29,7 +50,7 @@ A Model is a specific AI instance (like `gpt-4o` or `text-embedding-3-small`) th ### Adding a Model -1. Select a Provider from the list on the **Models** page. +1. Select a Provider from the list on the **Providers** page. 2. Click **Add Model** in the model list section. 3. Configure the following fields: diff --git a/docs/docs/getting-started/search-provider.md b/docs/docs/getting-started/search-provider.md index c84e776b..672a9594 100644 --- a/docs/docs/getting-started/search-provider.md +++ b/docs/docs/getting-started/search-provider.md @@ -45,7 +45,7 @@ Configure your search engines from the **Search Provider** page in the sidebar. ## Assigning a Search Provider to a Bot 1. Navigate to the **Bots** page and select your bot. -2. Go to the **Settings** tab. +2. Go to the **General** tab. 3. Find the **Search Provider** dropdown and select the provider you created. 4. Click **Save**. diff --git a/docs/docs/getting-started/sessions.md b/docs/docs/getting-started/sessions.md new file mode 100644 index 00000000..66430ae8 --- /dev/null +++ b/docs/docs/getting-started/sessions.md @@ -0,0 +1,85 @@ +# Sessions + +A **Session** is an independent conversation thread between a user and a bot. Each session maintains its own context window and message history, allowing the bot to focus on a specific topic or task without interference from other conversations. + +--- + +## Concept: Conversation Isolation + +When you chat with a bot, your messages are grouped into a session. The bot uses the session's history to maintain context. Starting a new session resets this context, giving you a fresh conversation without losing the previous one. + +Sessions are scoped per bot — each bot manages its own set of sessions independently. + +--- + +## Session Types + +Memoh uses four session types to separate different kinds of bot activity: + +| Type | Description | +|------|-------------| +| **Chat** | Standard user-initiated conversations. This is the default session type when chatting with a bot. | +| **Heartbeat** | Automatically created when a bot's heartbeat triggers. Contains the bot's periodic autonomous activity. | +| **Schedule** | Created when a scheduled task fires. Contains the bot's execution of a cron-triggered command. | +| **Subagent** | Created when the bot delegates a task to a subagent. Contains the subagent's independent work context. | + +Only **Chat** sessions are directly created by users. The other types are system-managed and appear as read-only records in the session list. + +--- + +## Starting a New Session with `/new` + +The `/new` slash command creates a fresh chat session, resetting the conversation context. This works across all channels: + +### In External Channels (Telegram, Discord, Feishu, etc.) + +Send `/new` as a message to the bot. The bot will: + +1. Create a new chat session. +2. Route all subsequent messages from you to this new session. +3. The previous session's history is preserved but no longer active. + +This is especially useful when: + +- You want to change topics without the bot referencing old context. +- The conversation has become too long and you want a clean start. +- You are switching between different tasks. + +### In the Web UI + +The Web UI provides a session sidebar where you can: + +- Click the **New Session** button to create a fresh chat session. +- Switch between existing sessions by clicking on them. +- Search sessions by content. +- Filter sessions by type (chat, heartbeat, schedule, subagent). +- Rename or delete sessions. + +--- + +## Managing Sessions + +### Viewing Sessions + +In the Web UI, the session sidebar lists all sessions for the currently selected bot. Each entry shows: + +- **Title** — The session name (auto-generated or user-defined). +- **Type** — The session type icon. +- **Last Activity** — When the session was last active. + +### Renaming Sessions + +Click on a session title to rename it. This helps organize conversations by topic. + +### Deleting Sessions + +Remove sessions you no longer need. Deleting a session removes its message history permanently. + +--- + +## How Sessions Relate to Other Features + +- **Heartbeat** sessions are created on each heartbeat trigger. You can view what the bot did during its autonomous activity by opening the corresponding heartbeat session. +- **Schedule** sessions are created when a scheduled task runs. Check these to see the results of cron-triggered commands. +- **Subagent** sessions track delegated tasks. They show the independent work context of each subagent invocation. +- **Memory** is shared across all sessions for a bot — memories extracted from one session are available in all others. diff --git a/docs/docs/getting-started/slash-commands.md b/docs/docs/getting-started/slash-commands.md new file mode 100644 index 00000000..464ef84c --- /dev/null +++ b/docs/docs/getting-started/slash-commands.md @@ -0,0 +1,238 @@ +# Slash Commands + +Memoh bots support **slash commands** — text commands prefixed with `/` that can be sent in any channel (Telegram, Discord, Feishu, Web, etc.) to perform administrative actions without going through the AI agent. + +Slash commands are intercepted before they reach the LLM, so they execute instantly and don't consume tokens. + +--- + +## Quick Reference + +| Command | Description | +|---------|-------------| +| `/help` | Show all available commands | +| `/new` | Start a new conversation session | +| `/schedule` | Manage scheduled tasks | +| `/mcp` | Manage MCP connections | +| `/settings` | View and update bot settings | +| `/model` | Manage bot models | +| `/memory` | Manage memory provider | +| `/search` | Manage search provider | +| `/browser` | Manage browser context | +| `/usage` | View token usage statistics | +| `/email` | View email configuration | +| `/heartbeat` | View heartbeat logs | +| `/skill` | View bot skills | +| `/fs` | Browse container filesystem | + +--- + +## Command Format + +Commands follow the pattern: + +``` +/resource [action] [arguments...] +``` + +- **resource** — The command group (e.g., `schedule`, `model`). +- **action** — The sub-command (e.g., `list`, `set`, `create`). Some commands have a default action. +- **arguments** — Additional parameters. Use quotes for values with spaces. + +Example: `/schedule create daily-report "0 9 * * *" "Send me a daily summary"` + +--- + +## Permissions + +Commands that modify bot settings are marked as **owner-only**. Only the bot owner can execute these commands. Read-only commands (listing, viewing) are available to all users who have chat access. + +Owner-only commands are marked with `[owner]` in the `/help` output. + +--- + +## Global Commands + +### `/help` + +Displays a list of all available commands and their usage. + +### `/new` + +Starts a new conversation session, resetting the current context. See [Sessions](/getting-started/sessions) for details. + +--- + +## `/schedule` — Manage Scheduled Tasks + +| Sub-command | Usage | Permission | +|-------------|-------|------------| +| `list` | `/schedule list` | All | +| `get` | `/schedule get ` | All | +| `create` | `/schedule create ` | Owner | +| `update` | `/schedule update [--pattern P] [--command C]` | Owner | +| `delete` | `/schedule delete ` | Owner | +| `enable` | `/schedule enable ` | Owner | +| `disable` | `/schedule disable ` | Owner | + +**Examples:** + +``` +/schedule list +/schedule create morning-news "0 9 * * *" "Summarize today's top tech news" +/schedule disable morning-news +``` + +--- + +## `/mcp` — Manage MCP Connections + +| Sub-command | Usage | Permission | +|-------------|-------|------------| +| `list` | `/mcp list` | All | +| `get` | `/mcp get ` | All | +| `delete` | `/mcp delete ` | Owner | + +--- + +## `/settings` — View and Update Bot Settings + +| Sub-command | Usage | Permission | +|-------------|-------|------------| +| `get` | `/settings` or `/settings get` | All | +| `update` | `/settings update [options]` | Owner | + +**Update options:** + +| Option | Values | +|--------|--------| +| `--language` | Language code (e.g., `en`, `zh`) | +| `--acl_default_effect` | `allow` or `deny` | +| `--reasoning_enabled` | `true` or `false` | +| `--reasoning_effort` | `low`, `medium`, or `high` | +| `--heartbeat_enabled` | `true` or `false` | +| `--heartbeat_interval` | Minutes (integer) | +| `--chat_model_id` | Model UUID | +| `--heartbeat_model_id` | Model UUID | + +**Example:** + +``` +/settings update --language en --heartbeat_enabled true --heartbeat_interval 30 +``` + +--- + +## `/model` — Manage Bot Models + +| Sub-command | Usage | Permission | +|-------------|-------|------------| +| `list` | `/model list` | All | +| `set` | `/model set ` | Owner | +| `set-heartbeat` | `/model set-heartbeat ` | Owner | + +**Example:** + +``` +/model list +/model set OpenAI gpt-4o +/model set-heartbeat OpenAI gpt-4o-mini +``` + +--- + +## `/memory` — Manage Memory Provider + +| Sub-command | Usage | Permission | +|-------------|-------|------------| +| `list` | `/memory list` | All | +| `set` | `/memory set ` | Owner | + +--- + +## `/search` — Manage Search Provider + +| Sub-command | Usage | Permission | +|-------------|-------|------------| +| `list` | `/search list` | All | +| `set` | `/search set ` | Owner | + +--- + +## `/browser` — Manage Browser Context + +| Sub-command | Usage | Permission | +|-------------|-------|------------| +| `list` | `/browser list` | All | +| `set` | `/browser set ` | Owner | + +--- + +## `/usage` — View Token Usage + +| Sub-command | Usage | Permission | +|-------------|-------|------------| +| `summary` | `/usage` or `/usage summary` | All | +| `by-model` | `/usage by-model` | All | + +Shows token usage for the last 7 days, broken down by session type (chat, heartbeat, schedule) or by model. + +--- + +## `/email` — View Email Configuration + +| Sub-command | Usage | Permission | +|-------------|-------|------------| +| `providers` | `/email providers` | All | +| `bindings` | `/email bindings` | All | +| `outbox` | `/email outbox` | All | + +--- + +## `/heartbeat` — View Heartbeat Logs + +| Sub-command | Usage | Permission | +|-------------|-------|------------| +| `logs` | `/heartbeat` or `/heartbeat logs` | All | + +Shows the 10 most recent heartbeat execution logs. + +--- + +## `/skill` — View Bot Skills + +| Sub-command | Usage | Permission | +|-------------|-------|------------| +| `list` | `/skill` or `/skill list` | All | + +--- + +## `/fs` — Browse Container Filesystem + +| Sub-command | Usage | Permission | +|-------------|-------|------------| +| `list` | `/fs list [path]` | All | +| `read` | `/fs read ` | All | + +**Examples:** + +``` +/fs list / +/fs list /home +/fs read /home/bot/IDENTITY.md +``` + +File content is truncated to 2000 characters when displayed in chat. + +--- + +## Mention-Prefixed Commands + +In group chats, you can prefix commands with a mention: + +``` +@BotName /help +@BotName /new +``` + +The bot will strip the mention and process the slash command normally. diff --git a/docs/docs/getting-started/subagents.md b/docs/docs/getting-started/subagents.md deleted file mode 100644 index ab9eed13..00000000 --- a/docs/docs/getting-started/subagents.md +++ /dev/null @@ -1,38 +0,0 @@ -# Bot Subagents - -Subagents are specialized AI entities with their own independent conversation context. They are managed by the main Bot to delegate complex tasks or focus on specific domains. - -## Concept: Task Specialization - -A **Subagent** is like a specialized teammate for your Bot. While the main Bot handles general conversation, it can spin up and communicate with a Subagent to perform deep analysis, research, or execution. - ---- - -## Fields - -Configure Subagents from the **Subagents** tab in the Bot Detail page. - -| Field | Description | -|-------|-------------| -| **Name** | The identifier for the subagent (e.g., "Research Assistant"). | -| **Description** | A brief explanation of the subagent's purpose and role. | -| **Skills** | A list of specific **Skills** assigned from the bot's container. | -| **Messages** | The conversation history and context specific to this subagent. | -| **Usage** | Statistics on token consumption and activity. | - ---- - -## Operations - -- **Add Subagent**: Create a new entity by providing a name and description. -- **Edit**: Update the name or description of an existing subagent. -- **Delete**: Permanently remove a subagent and its independent context. -- **View Context**: Open a dialog to inspect the subagent's conversation history and usage metrics. - ---- - -## Bot Interaction - -- The main Bot uses the **Subagent Tool** to create, communicate with, and receive results from subagents. -- Subagents inherit the main bot's container permissions but operate with their own "mental workspace." -- This modular approach allows for building multi-agent systems within a single Bot's scope. diff --git a/docs/docs/index.md b/docs/docs/index.md index 9f01fa85..368d939d 100644 --- a/docs/docs/index.md +++ b/docs/docs/index.md @@ -1,10 +1,10 @@ # Memoh Documentation -Memoh(/ˈmemoʊ/) is a multi-member, structured long-memory, containerized AI agent system. Create your own AI bots, chat with them via Telegram, Lark (Feishu), or Web. Each bot runs in an isolated container with its own memory system — able to edit files, run commands, and access the network. +Memoh(/ˈmemoʊ/) is a multi-member, structured long-memory, containerized AI agent system. Create your own AI bots, chat with them via Telegram, Discord, Lark (Feishu), QQ, Matrix, WeCom, WeChat, Email, or Web. Each bot runs in an isolated container with its own memory system — able to edit files, run commands, and access the network. ## Documentation - **[About Memoh](/about)** — What Memoh is, key features, and installation links. -- **[Installation](/installation/docker)** — [Docker](/installation/docker) (recommended) and [config.toml](/installation/config-toml) reference. +- **[Installation](/installation/docker)** — Docker setup (recommended). - **[Getting Started](/getting-started/provider-and-model)** — Step-by-step guide to configure models, bots, and channels. -- **[Channels](/channels/index)** — Detailed guides for Telegram, Feishu, and Discord. +- **[Channels](/channels/index)** — Detailed guides for Telegram, Feishu, Discord, QQ, Matrix, WeCom, and WeChat. diff --git a/docs/docs/installation/docker.md b/docs/docs/installation/docker.md index 01cb8665..14bfad1d 100644 --- a/docs/docs/installation/docker.md +++ b/docs/docs/installation/docker.md @@ -1,6 +1,6 @@ # Docker Installation -Docker is the recommended way to run Memoh. The stack includes PostgreSQL, Qdrant, the main server (with embedded Containerd), agent gateway, and web UI — all orchestrated via Docker Compose. You do not need to install containerd, nerdctl, or buildkit on your host; everything runs inside containers. +Docker is the recommended way to run Memoh. The stack includes PostgreSQL, the main server (with embedded Containerd and in-process AI agent), and the web UI — all orchestrated via Docker Compose. You do not need to install containerd, nerdctl, or buildkit on your host; everything runs inside containers. ## Service Architecture @@ -8,8 +8,7 @@ The Docker Compose stack consists of multiple services. Some are always started, | Service | Profile | Description | |---------|---------|-------------| -| **server** | *(core)* | Main Memoh server with embedded Containerd | -| **agent** | *(core)* | Agent gateway for bot execution | +| **server** | *(core)* | Main Memoh server with embedded Containerd and in-process AI agent | | **web** | *(core)* | Web UI (Vue 3) | | **postgres** | *(core)* | PostgreSQL database | | **qdrant** | `qdrant` | Qdrant vector database for memory search (sparse and dense modes) | @@ -82,13 +81,13 @@ Defaults when running silently: **Install a specific version:** ```bash -curl -fsSL https://memoh.sh | sudo sh -s -- --version v0.5.0 +curl -fsSL https://memoh.sh | sudo sh -s -- --version v0.6.0 ``` Or using the environment variable: ```bash -curl -fsSL https://memoh.sh | sudo MEMOH_VERSION=v0.5.0 sh +curl -fsSL https://memoh.sh | sudo MEMOH_VERSION=v0.6.0 sh ``` **Use China mainland mirror** (for slow image pulls): @@ -97,7 +96,7 @@ curl -fsSL https://memoh.sh | sudo MEMOH_VERSION=v0.5.0 sh curl -fsSL https://memoh.sh | sudo USE_CN_MIRROR=true sh ``` -> Environment variables can be combined, e.g. `curl -fsSL https://memoh.sh | sudo MEMOH_VERSION=v1.0.0 USE_CN_MIRROR=true sh` +> Environment variables can be combined, e.g. `curl -fsSL https://memoh.sh | sudo MEMOH_VERSION=v0.6.0 USE_CN_MIRROR=true sh` ## Manual Install @@ -155,13 +154,32 @@ After startup: |-----------------|------------------------| | Web UI | http://localhost:8082 | | API | http://localhost:8080 | -| Agent Gateway | http://localhost:8081 | | Browser Gateway | http://localhost:8083 | Default login: `admin` / `admin123` (change this in `config.toml`). First startup may take 1–2 minutes while images are pulled and services initialize. +## Configuration Reference + +The `config.toml` file controls all server behavior. Here is a summary of the available sections: + +| Section | Description | +|---------|-------------| +| `[log]` | Logging level and format (`info`, `debug`; `text`, `json`) | +| `[server]` | HTTP listen address (default `:8080`) | +| `[admin]` | Admin account credentials (username, password, email) | +| `[auth]` | JWT secret and token expiration | +| `timezone` | Server timezone (default `UTC`) | +| `[containerd]` | Containerd socket path and namespace | +| `[workspace]` | Container image, snapshotter, data paths, CNI config, optional registry mirror | +| `[postgres]` | PostgreSQL connection (host, port, user, password, database, sslmode) | +| `[qdrant]` | Qdrant vector database connection (base_url, api_key, timeout) | +| `[sparse]` | Sparse encoding service URL | +| `[registry]` | Provider definitions directory | +| `[browser_gateway]` | Browser Gateway host, port, and server address | +| `[web]` | Web frontend host and port | + ## Common Commands > Prefix with `sudo` on Linux if your user is not in the `docker` group. @@ -180,29 +198,7 @@ docker compose pull && docker compose up -d # Update to latest images |--------------------|--------------------|----------------------------------------------| | `POSTGRES_PASSWORD`| `memoh123` | PostgreSQL password (must match `postgres.password` in `config.toml`) | | `MEMOH_CONFIG` | `./config.toml` | Path to the configuration file | -| `MEMOH_VERSION` | *(latest release)* | Git tag to install (e.g. `v1.0.0`). Also pins Docker image versions. | -| `USE_CN_MIRROR` | `false` | Set to `true` to use China mainland mirror for Docker images | -| `BROWSER_CORES` | `chromium,firefox` | Browser engines to include in the browser image (`chromium`, `firefox`, or `chromium,firefox`) | -| `USE_SPARSE` | `false` | Set to `true` to enable the sparse memory service (`--profile sparse`) | - -## Production Checklist - -1. **Passwords** — Change all default passwords and secrets in `config.toml` -2. **HTTPS** — Configure SSL (e.g. via `docker-compose.override.yml` with certs or a reverse proxy) -3. **Firewall** — Restrict access to necessary ports -4. **Resource limits** — Set memory/CPU limits for containers -5. **Backups** — Regular backups of Postgres and Qdrant data - -## Troubleshooting - -```bash -docker compose logs server # View main service logs -docker compose config # Validate configuration -docker compose build --no-cache && docker compose up -d # Full rebuild -``` - -## Security Warnings - -- The main service runs with privileged container access — only run in trusted environments -- You must change all default passwords and secrets before production use -- Use HTTPS in production +| `MEMOH_VERSION` | *(latest release)* | Git tag to install (e.g. `v0.6.0`). Also pins Docker image versions. | +| `USE_CN_MIRROR` | `false` | Set to `true` to use China mainland image mirrors | +| `BROWSER_CORES` | `chromium,firefox` | Browser engines to include in the browser image | +| `BROWSER_TAG` | `latest` | Docker tag for the browser image | diff --git a/docs/docs/memory-providers/builtin.md b/docs/docs/memory-providers/builtin.md index dbc37d88..2d7d1535 100644 --- a/docs/docs/memory-providers/builtin.md +++ b/docs/docs/memory-providers/builtin.md @@ -97,7 +97,7 @@ base_url = "http://qdrant:6334" ## Assigning a Memory Provider to a Bot 1. Navigate to the **Bots** page and open your bot. -2. Go to the **Settings** tab. +2. Go to the **General** tab. 3. Find the **Memory Provider** dropdown. 4. Select the provider you created. 5. Click **Save**. diff --git a/docs/docs/memory-providers/index.md b/docs/docs/memory-providers/index.md index 92025b92..0ae95dfb 100644 --- a/docs/docs/memory-providers/index.md +++ b/docs/docs/memory-providers/index.md @@ -1,6 +1,6 @@ # Memory Providers -Memoh uses a **Memory Provider** to define how a bot stores, retrieves, and manages long-term memory. A bot can bind one memory provider in its **Settings** tab, and that provider becomes the backend for memory extraction and memory search. +Memoh uses a **Memory Provider** to define how a bot stores, retrieves, and manages long-term memory. A bot can bind one memory provider in its **General** tab, and that provider becomes the backend for memory extraction and memory search. ## Available Providers @@ -17,7 +17,7 @@ Memoh supports the following memory providers: 1. Open the **Memory Providers** page from the sidebar. 2. Create a provider instance using one of the supported provider types. 3. Configure the provider settings. -4. Open a bot's **Settings** tab and assign that provider in **Memory Provider**. +4. Open a bot's **General** tab and assign that provider in **Memory Provider**. 5. Manage actual memories from the bot's **Memory** tab. --- diff --git a/docs/docs/memory-providers/mem0.md b/docs/docs/memory-providers/mem0.md index 8ef8fe71..28f0c9a6 100644 --- a/docs/docs/memory-providers/mem0.md +++ b/docs/docs/memory-providers/mem0.md @@ -31,7 +31,7 @@ After creating a provider, select it from the list and configure its settings. ## Assigning a Mem0 Provider to a Bot 1. Navigate to the **Bots** page and open your bot. -2. Go to the **Settings** tab. +2. Go to the **General** tab. 3. Find the **Memory Provider** dropdown. 4. Select the Mem0 provider you created. 5. Click **Save**. diff --git a/docs/docs/memory-providers/openviking.md b/docs/docs/memory-providers/openviking.md index b2d07874..54bed072 100644 --- a/docs/docs/memory-providers/openviking.md +++ b/docs/docs/memory-providers/openviking.md @@ -29,7 +29,7 @@ After creating a provider, select it from the list and configure its settings. ## Assigning an OpenViking Provider to a Bot 1. Navigate to the **Bots** page and open your bot. -2. Go to the **Settings** tab. +2. Go to the **General** tab. 3. Find the **Memory Provider** dropdown. 4. Select the OpenViking provider you created. 5. Click **Save**. diff --git a/docs/docs/tts-providers/edge.md b/docs/docs/tts-providers/edge.md index ee2f8dc8..a6488377 100644 --- a/docs/docs/tts-providers/edge.md +++ b/docs/docs/tts-providers/edge.md @@ -30,7 +30,7 @@ Click the `edge-read-aloud` model to configure its settings. ## Assigning to a Bot -1. Open a bot's **Settings** tab. +1. Open a bot's **General** tab. 2. Find the **TTS Model** dropdown. 3. Select the configured Edge TTS model. 4. Click **Save**. diff --git a/docs/docs/tts-providers/index.md b/docs/docs/tts-providers/index.md index 822d5aa1..0f9779a0 100644 --- a/docs/docs/tts-providers/index.md +++ b/docs/docs/tts-providers/index.md @@ -15,7 +15,7 @@ Memoh supports **Text-to-Speech (TTS)** so bots can synthesize spoken audio from 3. Click **Create** — the provider's default model is auto-imported. 4. Click the model to configure voice, format, speed, and pitch. 5. Test synthesis with the built-in test button. -6. Open a bot's **Settings** tab and select the TTS Model. +6. Open a bot's **General** tab and select the TTS Model. 7. Save — the bot can now synthesize speech. ---