docs: update to v0.7

2026-04-25 07:00:48 +09:00 · 2026-04-16 17:45:11 +08:00
parent fc1ee59dea
commit 68b1efa343
22 changed files with 1449 additions and 454 deletions
@@ -6,7 +6,6 @@
 <div align="center">
  <img src="./assets/logo_title.png" alt="Memoh" height="100">
  <p>Self hosted, always-on AI agent platform run in containers.</p>
-  <p>📌 <a href="https://docs.memoh.ai/blogs/2026-02-16.html">Introduction to Memoh - The Case for an Always-On, Containerized Home Agent</a></p>
  <div align="center">
    <img src="https://img.shields.io/github/package-json/v/memohai/Memoh" alt="Version" />
    <img src="https://img.shields.io/github/license/memohai/Memoh" alt="License" />
@@ -27,7 +26,7 @@
  <hr>
 </div>

-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.
+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, Misskey, DingTalk, WeCom, WeChat, WeChat Official Account, 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

@@ -65,6 +64,17 @@ Visit <http://localhost:8082> after startup. Default login: `admin` / `admin123`

 See [DEPLOYMENT.md](DEPLOYMENT.md) for custom configuration and production setup.

+Documentation entry points:
+
+- [About Memoh](https://docs.memoh.ai/about)
+- [Providers & Models](https://docs.memoh.ai/getting-started/provider-and-model)
+- [Bot Setup](https://docs.memoh.ai/getting-started/bot)
+- [Sessions & Discuss Mode](https://docs.memoh.ai/getting-started/sessions)
+- [Channels](https://docs.memoh.ai/getting-started/channels)
+- [Skills](https://docs.memoh.ai/getting-started/skills)
+- [Supermarket](https://docs.memoh.ai/getting-started/supermarket)
+- [Slash Commands](https://docs.memoh.ai/getting-started/slash-commands)
+
 ## Why Memoh?

 Memoh is built for **always-on continuity** — an AI that stays online, and a memory that stays yours.
@@ -81,21 +91,22 @@ Memoh is built for **always-on continuity** — an AI that stays online, and a m

 - 🤖 **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.
+- 🧠 **Memory Engineering**: LLM-driven fact extraction, hybrid retrieval (dense + sparse + BM25), provider-based long-term memory, memory compaction, and separate session-level context compaction. Pluggable backends: Built-in (off / sparse / dense), [Mem0](https://mem0.ai), OpenViking.
+- 💬 **Broad Channel Coverage**: Telegram, Discord, Lark (Feishu), QQ, Matrix, Misskey, DingTalk, WeCom, WeChat, WeChat Official Account, Email (Mailgun / SMTP / Gmail OAuth), and built-in Web UI.

 ### 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.
+- 🎭 **Skills, Supermarket & Subagents**: Define bot behavior through modular skills, install curated skills and MCP templates from Supermarket, and delegate complex tasks to sub-agents with independent context.
+- 💭 **Sessions & Discuss Mode**: Use chat, discuss, schedule, heartbeat, and subagent sessions with slash-command control and session status inspection.
 - ⏰ **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.
+- 🔐 **Access Control**: Priority-based ACL rules with presets, allow/deny effects, and scope by channel identity, channel type, or conversation.
+- 🧪 **Multi-Model**: OpenAI-compatible, Anthropic, Google, OpenAI Codex, GitHub Copilot, and Edge TTS providers. 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
@@ -143,7 +154,7 @@ Additional capabilities include memory compaction (merge redundant entries), reb
 flowchart TB
    subgraph Clients [" Clients "]
        direction LR
-        CH["Channels<br/>Telegram · Discord · Feishu · QQ<br/>Matrix · WeCom · WeChat · Email"]
+        CH["Channels<br/>Telegram · Discord · Feishu · QQ · Matrix · Misskey<br/>DingTalk · WeCom · WeChat · WeChat OA · Email"]
        WEB["Web UI (Vue 3 :8082)"]
    end

@@ -7,7 +7,6 @@
  <img src="./assets/logo.png" alt="Memoh" width="100" height="100">
  <h1>Memoh</h1>
  <p>自托管、常驻运行的容器化 AI Agent 平台。</p>
-  <p>📌 <a href="https://docs.memoh.ai/blogs/2026-02-16.html">Introduction to Memoh - The Case for an Always-On, Containerized Home Agent</a></p>
  <div align="center">
    <img src="https://img.shields.io/github/package-json/v/memohai/Memoh" alt="Version" />
    <img src="https://img.shields.io/github/license/memohai/Memoh" alt="License" />
@@ -28,7 +27,7 @@
  <hr>
 </div>

-Memoh 是一个常驻运行的容器化 AI Agent 系统。你可以创建多个 AI 机器人，每个机器人运行在独立的容器中，拥有持久化记忆，并通过 Telegram、Discord、飞书(Lark)、QQ、Matrix、企业微信、微信、Email 或内置 Web 界面与之交互。机器人可以执行命令、编辑文件、浏览网页、通过 MCP 调用外部工具，并记住一切 —— 就像给每个 Bot 一台自己的电脑和大脑。
+Memoh 是一个常驻运行的容器化 AI Agent 系统。你可以创建多个 AI 机器人，每个机器人运行在独立的容器中，拥有持久化记忆，并通过 Telegram、Discord、飞书(Lark)、QQ、Matrix、Misskey、钉钉、企业微信、微信、微信公众号、Email 或内置 Web 界面与之交互。机器人可以执行命令、编辑文件、浏览网页、通过 MCP 调用外部工具，并记住一切 —— 就像给每个 Bot 一台自己的电脑和大脑。

 ## 快速开始

@@ -66,6 +65,17 @@ sudo docker compose up -d

 自定义配置与生产部署请参阅 [DEPLOYMENT.md](DEPLOYMENT.md)。

+文档入口：
+
+- [产品概览](https://docs.memoh.ai/about)
+- [Providers & Models](https://docs.memoh.ai/getting-started/provider-and-model)
+- [Bot 配置](https://docs.memoh.ai/getting-started/bot)
+- [Sessions / Discuss 模式](https://docs.memoh.ai/getting-started/sessions)
+- [Channels 渠道接入](https://docs.memoh.ai/getting-started/channels)
+- [Skills](https://docs.memoh.ai/getting-started/skills)
+- [Supermarket](https://docs.memoh.ai/getting-started/supermarket)
+- [Slash Commands](https://docs.memoh.ai/getting-started/slash-commands)
+
 ## 为什么选择 Memoh？

 Memoh 为**常驻连续运行**而生 —— 一个始终在线的 AI，一份属于你自己的记忆。
@@ -82,21 +92,22 @@ Memoh 为**常驻连续运行**而生 —— 一个始终在线的 AI，一份

 - 🤖 **多 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 界面 —— 统一流式输出、富文本和附件支持。
+- 🧠 **记忆工程**：LLM 驱动的知识抽取，混合检索（稠密 + 稀疏 + BM25），基于 Provider 的长期记忆、记忆压缩，以及独立的会话上下文压缩。可插拔后端：内置（off / sparse / dense）、[Mem0](https://mem0.ai)、OpenViking。
+- 💬 **广泛渠道接入**：Telegram、Discord、飞书(Lark)、QQ、Matrix、Misskey、钉钉、企业微信、微信、微信公众号、Email（Mailgun / SMTP / Gmail OAuth）及内置 Web 界面。

 ### Agent 能力

 - 🔧 **MCP（模型上下文协议）**：完整 MCP 支持（HTTP / SSE / Stdio / OAuth）。连接外部工具服务器进行扩展，每个 Bot 独立管理自己的 MCP 连接。
 - 🌐 **浏览器自动化**：基于 Playwright 的无头 Chromium/Firefox —— 页面导航、点击、填写表单、截图、读取无障碍树、多标签页管理。
- 🎭 **技能与子代理**：通过模块化技能文件定义 Bot 人格；将复杂任务委派给拥有独立上下文的子代理。
+- 🎭 **技能、Supermarket 与子代理**：通过模块化技能文件定义 Bot 行为；从 Supermarket 安装精选技能和 MCP 模板；将复杂任务委派给拥有独立上下文的子代理。
+- 💭 **会话与 Discuss 模式**：支持 chat、discuss、schedule、heartbeat、subagent 等会话类型，并可通过 slash commands 管理。
 - ⏰ **自动化**：基于 Cron 的定时任务和周期性心跳，实现 Bot 自主活动。

 ### 管理

 - 🖥️ **Web 界面**：基于 Vue 3 + Tailwind CSS 的现代面板 —— 流式聊天、工具调用可视化、文件管理器、所有配置可视化操作。深色/浅色主题，中英文支持。
- 🔐 **访问控制**：基于优先级的 ACL 规则，支持 allow/deny 效果，可按渠道身份、渠道类型或会话维度控制。
- 🧪 **多模型**：兼容任何 OpenAI 兼容、Anthropic 或 Google 提供商。每个 Bot 独立配置模型，支持 Provider OAuth 和自动模型导入。
+- 🔐 **访问控制**：基于优先级的 ACL 规则与 preset，支持 allow/deny 效果，可按渠道身份、渠道类型或会话维度控制。
+- 🧪 **多模型**：支持 OpenAI 兼容、Anthropic、Google、OpenAI Codex、GitHub Copilot、Edge TTS 等提供商。每个 Bot 独立配置模型，支持 Provider OAuth 和自动模型导入。
 - 🚀 **一键部署**：Docker Compose 编排，自动迁移、containerd 初始化与 CNI 网络配置。

 ## 记忆系统
@@ -144,7 +155,7 @@ Memoh 的记忆系统围绕 **Memory Provider（记忆供应商）** 构建 —
 flowchart TB
    subgraph Clients [" 客户端 "]
        direction LR
-        CH["渠道<br/>Telegram · Discord · 飞书 · QQ<br/>Matrix · 企业微信 · 微信 · Email"]
+        CH["渠道<br/>Telegram · Discord · 飞书 · QQ · Matrix · Misskey<br/>钉钉 · 企业微信 · 微信 · 微信公众号 · Email"]
        WEB["Web 界面 (Vue 3 :8082)"]
    end

@@ -48,6 +48,10 @@ export const en = [
        text: 'Skills',
        link: '/getting-started/skills.md'
      },
+      {
+        text: 'Supermarket',
+        link: '/getting-started/supermarket.md'
+      },
      {
        text: 'MCP',
        link: '/getting-started/mcp.md'
@@ -151,6 +155,14 @@ export const en = [
        text: 'Matrix',
        link: '/channels/matrix.md'
      },
+      {
+        text: 'Misskey',
+        link: '/channels/misskey.md'
+      },
+      {
+        text: 'DingTalk',
+        link: '/channels/dingtalk.md'
+      },
      {
        text: 'WeCom (WeWork)',
        link: '/channels/wecom.md'
@@ -159,6 +171,10 @@ export const en = [
        text: 'WeChat',
        link: '/channels/weixin.md'
      },
+      {
+        text: 'WeChat Official Account',
+        link: '/channels/wechatoa.md'
+      },
    ]
  },
 ]
@@ -2,5 +2,68 @@ export const zh = [
  {
    text: '文档总览',
    link: '/zh/index.md'
-  }
+  },
+  {
+    text: '常用入口（英文）',
+    items: [
+      {
+        text: '产品概览',
+        link: '/about.md'
+      },
+      {
+        text: 'Docker 安装',
+        link: '/installation/docker.md'
+      },
+      {
+        text: 'Providers And Models',
+        link: '/getting-started/provider-and-model.md'
+      },
+      {
+        text: 'Bot 配置',
+        link: '/getting-started/bot.md'
+      },
+      {
+        text: 'Sessions / Discuss',
+        link: '/getting-started/sessions.md'
+      },
+      {
+        text: 'Channels',
+        link: '/getting-started/channels.md'
+      },
+      {
+        text: 'Skills',
+        link: '/getting-started/skills.md'
+      },
+      {
+        text: 'Supermarket',
+        link: '/getting-started/supermarket.md'
+      },
+      {
+        text: 'Slash Commands',
+        link: '/getting-started/slash-commands.md'
+      },
+    ]
+  },
+  {
+    text: '中文概念',
+    items: [
+      {
+        text: '核心概念',
+        link: '/zh/concepts/index.md'
+      },
+      {
+        text: '账号模型与绑定',
+        link: '/zh/concepts/identity-and-binding.md'
+      },
+    ]
+  },
+  {
+    text: '维护规范',
+    items: [
+      {
+        text: '术语规范',
+        link: '/zh/style/terminology.md'
+      },
+    ]
+  },
 ]
@@ -1,114 +1,118 @@
 # About Memoh

-## What is Memoh?
+## 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), 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.
+Memoh is a multi-member, structured long-memory, containerized AI agent platform. You can create multiple AI bots, give each bot its own isolated workspace and long-term memory, and interact with them through Telegram, Discord, Lark (Feishu), QQ, Matrix, Misskey, DingTalk, WeCom, WeChat, WeChat Official Account, Email, or the built-in Web UI.

-## Key Features
+Every bot has its own execution environment, tools, memory configuration, and channel integrations. In practice, that means each bot behaves more like its own computer-backed agent than a shared chat preset.

-### Multi-Bot Management
+## What Makes Memoh Different

-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-Bot And Multi-User

-### Multi-User & Identity Recognition
+Memoh is built for real sharing and real separation at the same time:

-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.
+- create multiple bots for different roles or people
+- let humans and bots interact in private chats, groups, or delegated workflows
+- distinguish individual users in shared conversations
+- bind identities across channels so the same person can be recognized consistently

-### Containerized Isolation
+### Containerized Workspaces

-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.
+Each bot runs in its own isolated container workspace with a separate filesystem and network boundary. Bots can read and write files, run commands, and use tools inside that workspace without interfering with other bots.

-### Memory Engineering
+### Long-Term Memory And Context Management

-A deeply engineered memory layer:
+Memoh separates two different problems:

- 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)
- Loads the last 24 hours of conversation context by default
- Automatic memory compaction and rebuild capabilities
- Multi-language auto-detection
+- **Long-term memory** stores durable facts and recalls them across conversations through memory providers
+- **Session context compaction** reduces the prompt size of an active session when the current conversation gets too large

-### Multi-Platform Support
+This distinction is important: context compaction changes the active session window, while memory compaction rewrites stored memory entries.

-Unified channel adapter architecture for connecting to multiple messaging platforms:
+### Sessions And Discuss Mode

- **Telegram** — Full support with streaming, Markdown, attachments, and replies
- **Discord** — Full support
- **Lark (Feishu)** — Full support
- **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
+Each bot maintains independent **sessions** that preserve context. Memoh currently uses five session types:

-### Agent Capabilities
+- **Chat** — regular user-facing conversations
+- **Discuss** — deliberative sessions where the bot can think through work and decide what to send outward
+- **Heartbeat** — periodic autonomous sessions
+- **Schedule** — cron-triggered task sessions
+- **Subagent** — delegated task sessions

-Bots come with a rich set of built-in tools:
+You can start or route sessions with slash commands such as `/new`, and the Web UI exposes a session status panel with metrics like context usage, cache hit rate, and used skills.

- **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 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
- **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
+### Broad Channel Coverage

-### Sessions
+Memoh uses a unified channel adapter system so one bot can be reachable from many places at once.

-Each bot maintains **sessions** — independent conversation threads that preserve context. Sessions come in four types:
+Current user-facing integrations include:

- **Chat** — Standard user conversations
- **Heartbeat** — Periodic autonomous activity sessions
- **Schedule** — Cron-triggered task execution sessions
- **Subagent** — Delegated task sessions for sub-agents
+- **Telegram**
+- **Discord**
+- **Lark (Feishu)**
+- **QQ**
+- **Matrix**
+- **Misskey**
+- **DingTalk**
+- **WeCom**
+- **WeChat**
+- **WeChat Official Account**
+- **Email**
+- **Web**

-Users can start a new session at any time using the `/new` slash command in any channel, which resets the conversation context.
+Memoh also distinguishes between the personal **WeChat** QR-login integration and the webhook-based **WeChat Official Account** integration.

-### Slash Commands
+### Tools, Skills, MCP, And Supermarket

-Bots support a comprehensive set of slash commands that can be used directly in any channel:
+Bots can use a rich set of built-in capabilities, including:

- `/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.
+- web search and web fetch
+- browser automation
+- file editing and command execution inside the bot workspace
+- memory search and management
+- messaging, email, and TTS
+- subagents for delegated work
+- **skills** for reusable behavior modules
+- **MCP** connections for external tool servers
+- **Supermarket** for curated skill and MCP template installation

-### Multi-LLM Provider Support
+### Providers And Models

-Flexibly switch between a wide range of LLM providers via four client types:
+Memoh supports multiple provider client types, including:

- OpenAI Responses API, OpenAI Chat Completions API (including compatible services)
- Anthropic Messages API, Google Generative AI API
+- OpenAI-compatible chat completions
+- OpenAI Responses API
+- Anthropic Messages
+- Google Generative AI
+- OpenAI Codex
+- GitHub Copilot
+- Edge Speech / TTS

-Per-bot model assignment for chat, memory, and embedding. Providers support OAuth authentication and automatic model import.
+Models are also separated by role:

-### MCP Protocol Support
+- **chat** models for normal interaction
+- **embedding** models for vector memory and search
+- **speech** models for TTS

-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.
+Image generation is configured through compatible chat/image models rather than a separate image-provider system.

-### Scheduled Tasks
+### Operations And UI

-Configure scheduled tasks using cron expressions to automatically run commands at specified times. Supports max execution count limits and manual triggers.
+The Web UI is designed so you can manage the whole system without editing config files by hand every day. It includes:

-### Memory Compaction
+- bot configuration tabs for general settings, access, channels, heartbeat, compaction, and more
+- provider and model management with OAuth flows where supported
+- session-side controls such as immediate compaction and status inspection
+- skill management with effective / shadowed / disabled visibility
+- slash-command driven control from channels

-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.
+## Where To Start

-### Graphical Configuration
-
-Modern web UI (Vue 3 + Tailwind CSS) with real-time streaming chat, tool call visualization, container filesystem browser, and visual configuration for bots, channels, providers, models, MCP, skills, and all other settings. Dark/light theme, i18n. No coding required to set up your own AI bot.
-
-## Installation
-
-To get Memoh running:
-
- **[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.
+- **[Docker Installation](/installation/docker)** — get the stack running
+- **[Providers And Models](/getting-started/provider-and-model)** — configure model access
+- **[Bot Setup](/getting-started/bot)** — create and configure a bot
+- **[Sessions](/getting-started/sessions)** — understand chat vs discuss behavior
+- **[Channels](/getting-started/channels)** — choose where bots are reachable
+- **[Skills](/getting-started/skills)** and **[Supermarket](/getting-started/supermarket)** — extend what bots can do
+- **[Slash Commands](/getting-started/slash-commands)** — operate bots directly from chat
@@ -0,0 +1,43 @@
+# DingTalk Channel Configuration
+
+Memoh supports DingTalk bots for private chats and group chats. The adapter uses DingTalk's stream connection for inbound events and the official APIs for outbound replies and media.
+
+## Step 1: Create A DingTalk App
+
+1. Open the DingTalk developer platform for your organization.
+2. Create or choose the app that will act as your bot.
+3. Enable the bot / messaging capability for that app.
+4. Copy the app credentials:
+   - **App Key**
+   - **App Secret**
+
+Depending on your DingTalk environment, you may also need to grant message permissions and publish the app before it is available to end users.
+
+## Step 2: Configure Memoh
+
+1. Open your bot in the Memoh Web UI.
+2. Go to **Platforms**.
+3. Click **Add Channel** and choose **DingTalk**.
+4. Fill in **App Key** and **App Secret**.
+5. Click **Save and Enable**.
+
+Memoh maintains the DingTalk stream connection automatically. For the normal setup, you do not need to manually paste a webhook callback URL.
+
+## Step 3: Verify Messaging
+
+After the channel is enabled:
+
+1. Send a private message to the DingTalk bot, or mention it in a supported group chat.
+2. Confirm the bot receives the message and can reply.
+
+## Features Supported
+
+- **Private chats**
+- **Group chats**
+- **Text and Markdown-style output**
+- **Replies**
+- **Attachments and media**
+
+Current behavior note:
+
+- Outbound responses are non-streaming on DingTalk in Memoh.
@@ -9,16 +9,34 @@ Memoh currently supports the following channels:
 - **[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.
 - **[Matrix](./matrix)**: Decentralized messaging protocol support for any Matrix homeserver.
+- **[Misskey](./misskey)**: Federated social/chat style integration with replies and reactions.
+- **[DingTalk](./dingtalk)**: Enterprise chat integration for private and group conversations.
 - **[WeCom (WeWork)](./wecom)**: Enterprise messaging integration for WeCom workspaces.
- **[WeChat](./weixin)**: Personal messaging via the WeChat AI bot platform.
+- **[WeChat](./weixin)**: Personal messaging via QR login.
+- **[WeChat Official Account](./wechatoa)**: Official account webhook integration for private message scenarios.
 - **Email**: Connect via SMTP providers, Mailgun, or Gmail OAuth (configured through Email Providers).
 - **Web**: Built-in chat interface for immediate access.

+### WeChat vs WeChat Official Account
+
+Memoh supports two different WeChat-related adapters:
+
+- **WeChat (`weixin`)** is the personal-account style integration that relies on QR login.
+- **WeChat Official Account (`wechatoa`)** is the official-account / webhook style integration that uses `App ID`, `App Secret`, `Token`, and optional AES settings.
+
+Choose the one that matches your actual WeChat deployment model.
+
 ## 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 **Platforms** tab and paste the credentials.
-4. **Enable**: Activate the channel to start receiving and sending messages.
+1. **Create an external app/bot**: Register your bot on the target platform.
+2. **Obtain credentials**: Fetch API tokens, App IDs, app secrets, or access tokens.
+3. **Configure in Memoh**: Add the channel from your bot's **Platforms** tab.
+4. **Save and enable**: Activate the channel to start receiving and sending messages.
+
+Depending on the platform, the final step may involve:
+
+- copying a webhook callback URL into the platform console
+- approving a QR login on mobile
+- leaving a long-lived stream/WebSocket connection running through Memoh

 Choose a channel from the sidebar to see detailed configuration guides for each platform.
@@ -0,0 +1,49 @@
+# Misskey Channel Configuration
+
+Memoh can connect a bot to a Misskey server so it can read inbound mentions and reply as a Misskey account. This adapter is best for text-first social interactions on self-hosted or public Misskey instances.
+
+## Step 1: Prepare A Misskey Account And Token
+
+1. Sign in to the Misskey instance you want to use.
+2. Create or choose the account that should represent your bot.
+3. Generate an **Access Token** for that account.
+
+Memoh needs:
+
+- **Instance URL**: for example `https://misskey.io`
+- **Access Token**: a token for the bot account
+
+The exact token-creation UI varies by Misskey instance. Make sure the token is allowed to read inbound events for the bot account and publish replies.
+
+## Step 2: Configure Memoh
+
+1. Open your bot in the Memoh Web UI.
+2. Go to **Platforms**.
+3. Click **Add Channel** and choose **Misskey**.
+4. Enter the **Instance URL**.
+5. Paste the **Access Token**.
+6. Click **Save and Enable**.
+
+Memoh uses these credentials to discover the bot identity and start the Misskey connection.
+
+## Step 3: Start Chatting
+
+After the channel is enabled, users can interact with the bot on that Misskey instance.
+
+Misskey in Memoh is generally best suited for:
+
+- replies to users
+- text and Markdown-style output
+- reaction-aware social conversations
+
+## Features Supported
+
+- **Text**
+- **Markdown**
+- **Replies**
+- **Reactions**
+
+Current limitations:
+
+- **No attachments / media upload**
+- **No streaming output**
@@ -0,0 +1,59 @@
+# WeChat Official Account Channel Configuration
+
+This guide covers the **WeChat Official Account** adapter in Memoh. It is different from the personal **WeChat** QR-login adapter: this one is for official-account webhook integration and is intended for inbound private-message scenarios.
+
+## Step 1: Prepare Official Account Credentials
+
+From the WeChat Official Account platform, prepare:
+
+- **App ID**
+- **App Secret**
+- **Token**
+
+You may also need:
+
+- **Encoding AES Key** if you use encrypted webhook delivery
+- an outbound **HTTP Proxy URL** if your deployment must reach WeChat APIs through a proxy
+
+## Step 2: Add The Channel In Memoh
+
+1. Open your bot in the Memoh Web UI.
+2. Go to **Platforms**.
+3. Click **Add Channel** and choose **WeChat Official Account**.
+4. Fill in the required fields:
+   - **App ID**
+   - **App Secret**
+   - **Token**
+5. Choose the **Encryption Mode**.
+6. If you use `safe` or `compat` mode, also provide the **Encoding AES Key**.
+7. Save the channel.
+
+Memoh generates a **Webhook Callback URL** after the channel has been saved.
+
+## Step 3: Configure The WeChat Platform
+
+1. Copy the **Webhook Callback URL** from Memoh.
+2. Paste it into the WeChat Official Account platform callback configuration.
+3. Make sure the WeChat platform and Memoh use the same:
+   - **Token**
+   - **Encryption Mode**
+   - **Encoding AES Key** when encryption is enabled
+
+WeChat will verify the callback before delivering real messages.
+
+## Step 4: Enable And Test
+
+1. Enable the channel in Memoh.
+2. Send a test private message from the official account side.
+3. Confirm that Memoh receives the message and the bot can reply.
+
+## Features Supported
+
+- **Private chats**
+- **Replies**
+- **Attachments and media**
+
+Current behavior notes:
+
+- This adapter is intended for **private-message** conversations, not group-style chats.
+- Outbound responses are non-streaming on this channel.
@@ -4,11 +4,27 @@ Memoh uses an ACL (Access Control List) system to control who can interact with

 ---

+## Quick Start: ACL Presets
+
+When you create a bot, Memoh lets you start from an **ACL preset**. Presets are just a shortcut for common access patterns.
+
+| Preset | Result |
+|--------|--------|
+| `allow_all` | Default effect is `allow`; anyone can chat unless you add deny rules later |
+| `private_only` | Default effect is `deny`; private conversations are allowed |
+| `group_only` | Default effect is `deny`; group conversations are allowed |
+| `group_and_thread_only` | Default effect is `deny`; groups and threads are allowed |
+| `deny_all` | Default effect is `deny`; nobody except the owner/admin path can chat until you add allow rules |
+
+These presets only define the starting point. After creation, you can refine everything from the **Access** tab.
+
+---
+
 ## Concepts

 ### Default Effect

-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**.
+Each bot has a **default effect** (`allow` or `deny`) that applies when no ACL rule matches an incoming message. Configure this from the bot's **Access** tab.

 - **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.
@@ -47,6 +63,15 @@ This means rule ordering matters. A deny rule placed above an allow rule will ta

 Open a bot's **Access** tab to configure its access control.

+### Start With A Preset, Then Refine
+
+Recommended workflow:
+
+1. Pick an ACL preset when creating the bot.
+2. Open the **Access** tab.
+3. Confirm the resulting **Default Effect**.
+4. Add or reorder rules only where the preset is too broad or too narrow.
+
 ### Adding Rules

 1. Click **Add Rule**.
@@ -78,28 +103,42 @@ Scope fields form a hierarchy: **Channel → Conversation Type → Conversation

 ---

+## What The Presets Actually Mean
+
+This is the most useful mental model:
+
+- `allow_all` is best for open bots and public demos.
+- `private_only` is best when the bot should only answer in direct chats.
+- `group_only` is best for bots intended to live only in shared rooms.
+- `group_and_thread_only` is best for bots that should work in group spaces and threaded sub-conversations, but not in private DMs.
+- `deny_all` is best for highly restricted bots where you want to add every allow rule manually.
+
+If you are unsure, start with `allow_all` for a personal test bot or `deny_all` for anything sensitive.
+
+---
+
 ## Examples

 ### Open Bot (Anyone Can Chat)

-1. Set **ACL Default Effect** to `allow` in the **General** tab.
+1. Choose preset `allow_all`, or set **ACL Default Effect** to `allow`.
 2. No rules needed — everyone is allowed by default.

 ### Private Bot with Selected Users

-1. Set **ACL Default Effect** to `deny`.
+1. Choose preset `deny_all`, or 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.

 ### Open Bot with Blocked Users

-1. Set **ACL Default Effect** to `allow`.
+1. Choose preset `allow_all`, or 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`.
+1. Start from preset `deny_all` or `private_only`, depending on your goal.
 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.

@@ -108,3 +147,14 @@ Scope fields form a hierarchy: **Channel → Conversation Type → Conversation
 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.
+
+---
+
+## Debugging Access Decisions
+
+When ACL behavior is confusing, use:
+
+- the **Access** tab to inspect rule order and default effect
+- the `/access` slash command to inspect the current identity, role, and ACL evaluation context
+
+This is especially helpful when a user is linked across multiple channels or when group/thread scoping is involved.
@@ -7,8 +7,10 @@ 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 chats.
-    - **Avatar**: A URL for the bot's profile picture.
+   - **Display Name**: The name users will see in chats.
+   - **Avatar**: A URL for the bot's profile picture.
+   - **Timezone**: Optional per-bot timezone. If left empty, the bot inherits the user or system timezone.
+   - **ACL Preset**: Quick-start access policy such as `allow_all` or `private_only`.
 4. Click **Create**.

 ---
@@ -22,17 +24,17 @@ Once created, clicking on a bot card takes you to its **Detail Page**, where you
 | Tab | Description |
 |-----|-------------|
 | **Overview** | Health checks for container, database, channels, and memory. |
-| **General** | Core settings: models, providers, reasoning, heartbeat, compaction, and danger zone. |
+| **General** | Core runtime settings: chat/title/image models, memory/search/browser/TTS bindings, timezone, language, reasoning, 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. |
+| **Platforms** | Channel configurations such as Telegram, Discord, Feishu, QQ, Matrix, WeCom, WeChat, Misskey, DingTalk, and Web. |
+| **Access** | ACL rules and default access behavior. |
 | **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. |
+| **Heartbeat** | Heartbeat configuration, model selection, and execution logs. |
+| **Compaction** | Session context compaction settings and logs. |
 | **Schedule** | Cron-based scheduled tasks and execution logs. |
 | **Skills** | Markdown-based skill files that define bot personality and capabilities. |

@@ -40,45 +42,99 @@ Once created, clicking on a bot card takes you to its **Detail Page**, where you

 ## 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.
+After creating a bot, the most important step is configuring its runtime settings. These settings are split across a few tabs instead of living in one giant form.

 1. Navigate to your bot's **Detail Page**.
-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.
-   - **Search Provider**: Select the search engine provider for web search.
-   - **Browser Context**: Select the browser profile the bot should use for browser automation.
-4. Click **Save** at the bottom of the form.
+2. Start with the **General** tab for chat/runtime bindings.
+3. Use the **Heartbeat** tab for scheduled autonomous activity.
+4. Use the **Compaction** tab for session context compaction behavior.
+5. Use the **Access** tab to refine ACL rules after the initial ACL preset.

 If you have not created these resources yet, set them up first:

- [LLM Provider and Model](/getting-started/provider-and-model.md)
+- [Providers And Models](/getting-started/provider-and-model.md)
 - [Built-in Memory Provider](/memory-providers/builtin.md)
 - [Search Providers](/getting-started/search-provider.md)
 - [Browser Contexts](/getting-started/browser.md)
+- [TTS Providers](/tts-providers/index.md)

 ---

 ## General Tab Reference

-The **General** tab contains all the core parameters that define your bot's behavior and runtime configuration.
+The **General** tab contains the settings that shape everyday conversation behavior.

 | Field | Description |
 |-------|-------------|
 | **Chat Model** | The main LLM used for generating chat responses. |
+| **Title Model** | Optional model used to generate session titles. |
+| **Image Generation Model** | Optional model used by image-generation features. Pick a chat model that supports `image-output`. |
 | **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. |
+| **TTS Model** | Optional speech model used for text-to-speech output. Speech models come from the TTS Providers flow, not the normal chat provider flow. |
 | **Browser Context** | The browser environment used for web automation, such as viewport, locale, and mobile behavior. |
+| **Timezone** | Per-bot timezone. If empty, Memoh inherits the user timezone and then falls back to the system timezone. |
 | **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 Enabled** | Available when the selected chat model exposes `reasoning` compatibility. |
 | **Reasoning Effort** | Set the level of reasoning effort (`low`, `medium`, `high`). |
-| **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. |
+
+Notes:
+
+- The **Image Generation Model** is intentionally separate from the normal chat model so you can dedicate an image-capable model only to visual generation tasks.
+- The **TTS Model** comes from the [TTS Providers](/tts-providers/index.md) system and uses `speech` models such as Edge TTS voices.
+- The selected chat model's `context_window` influences session status reporting and [Context Compaction](/getting-started/compaction).
+
+---
+
+## Heartbeat Tab Reference
+
+Heartbeat is configured from its own tab.
+
+| Field | Description |
+|-------|-------------|
+| **Heartbeat Enabled** | Enable or disable periodic autonomous activity. |
+| **Heartbeat Interval** | How often the heartbeat runs, in minutes. |
+| **Heartbeat Model** | Optional dedicated model for heartbeat tasks. This can differ from the main chat model. |
+
+The Heartbeat tab also includes heartbeat execution logs, so you can review what the bot did during autonomous runs.
+
+---
+
+## Compaction Tab Reference
+
+Compaction is now about **session context compaction**, not memory maintenance.
+
+| Field | Description |
+|-------|-------------|
+| **Compaction Enabled** | Enable or disable automatic context compaction. |
+| **Compaction Threshold** | Estimated token threshold that triggers compaction. |
+| **Compaction Ratio** | How aggressively the session context should be reduced. |
+| **Compaction Model** | Optional dedicated model used to summarize old session context. |
+
+The Compaction tab also exposes compaction logs so you can see recent successful, pending, or failed runs.
+
+For the runtime behavior, see [Context Compaction](/getting-started/compaction).
+
+---
+
+## Access And ACL
+
+At creation time, the bot starts from an **ACL preset**. After that, use the **Access** tab for fine-grained control.
+
+Two layers matter:
+
+- **ACL Preset** gives you a sensible starting policy for a new bot.
+- **ACL Default Effect** controls the default result when no rule matches.
+
+Use the **Access** tab to refine conversation, group, and thread rules after the initial setup.
+
+---
+
+## Discuss-Related Advanced Settings
+
+Most users only need the `chat` and `discuss` behavior described in [Sessions](/getting-started/sessions).
+
+If you manage bot settings through the API or custom automation, the settings schema also includes `discuss_probe_model_id` for discuss-mode specific setups. Treat it as an advanced setting rather than a required field for normal bot creation.

 ---

@@ -14,15 +14,23 @@ Configure your bot's connections from the **Platforms** tab in the Bot Detail pa

 ### Platform Guides

-For detailed step-by-step guides on how to create and configure bots for each platform, see:
+| Platform | Guide | Notes |
+|----------|-------|-------|
+| Telegram | [Telegram Configuration](/channels/telegram) | Strong attachment and streaming support |
+| Feishu (Lark) | [Feishu Configuration](/channels/feishu) | Supports webhook-style inbound mode |
+| Discord | [Discord Configuration](/channels/discord) | Good fit for communities and servers |
+| QQ | [QQ Configuration](/channels/qq) | Personal DM oriented |
+| Matrix | [Matrix Configuration](/channels/matrix) | Decentralized homeserver support |
+| Misskey | [Misskey Configuration](/channels/misskey) | Replies and reactions, no streaming |
+| DingTalk | [DingTalk Configuration](/channels/dingtalk) | Enterprise private/group chat |
+| WeCom (WeWork) | [WeCom Configuration](/channels/wecom) | Enterprise workspace integration |
+| WeChat | [WeChat Configuration](/channels/weixin) | Personal QR login flow |
+| WeChat Official Account | [WeChat Official Account Configuration](/channels/wechatoa) | Official account webhook flow |

- **[Telegram Configuration](/channels/telegram)**
- **[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)**
+Two WeChat adapters exist on purpose:
+
+- **WeChat** is the QR-login personal messaging integration.
+- **WeChat Official Account** is the official account / webhook integration for private-message scenarios.

 ---

@@ -49,12 +57,27 @@ 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
+### 4. Special Case: WeChat QR Login

 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.

+### 5. Special Case: WeChat Official Account Webhook
+
+If using **WeChat Official Account**:
+1. Create and save the channel first.
+2. Memoh generates a **Webhook Callback URL** for that channel.
+3. Copy the callback URL into the WeChat Official Account platform configuration.
+4. Keep the configured `Token`, `Encryption Mode`, and optional AES settings aligned between Memoh and WeChat.
+
+### 6. Special Case: DingTalk Stream Connection
+
+If using **DingTalk**:
+1. Configure `App Key` and `App Secret`.
+2. Save and enable the channel.
+3. Memoh maintains the stream connection for inbound events; you do not need to manage a separate webhook callback URL for the standard setup.
+
 ---

 ## Operations
@@ -1,75 +1,134 @@
-# Memory Compaction
+# Context 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.
+**Context Compaction** reduces the prompt footprint of a single conversation session by summarizing older turns and keeping the active context smaller.
+
+This page is about **session context**, not long-term memory storage. If you want to merge or rewrite stored memories in a memory provider, see [Bot Memory Management](/getting-started/memory).

 ---

-## Concept: Why Compact?
+## Why It Exists

-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:
+As a conversation grows, the bot needs to send more prior messages back to the model. That increases:

- **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.
+- token usage
+- latency
+- pressure on the model's context window
+- the chance that older but still important turns will crowd out newer ones
+
+Context compaction helps by replacing older conversational detail with a shorter summary that still preserves enough continuity for the next turns.

 ---

-## Configuration
+## What It Changes

-Configure compaction from the **General** tab in the Bot Detail page.
+Context compaction affects the **active session context** only.
+
+It does **not**:
+
+- delete the bot itself
+- change the configured memory provider
+- merge long-term memory records
+- replace the need for memory search
+
+In practice, it changes how much historical session text is carried into future model calls.
+
+---
+
+## Automatic Compaction
+
+Configure automatic context compaction from the bot's **General** tab.
+
+Relevant fields:

 | 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. |
+| **Compaction Enabled** | Enable or disable automatic context compaction for this bot. |
+| **Compaction Threshold** | Estimated token threshold that triggers background compaction. |
+| **Compaction Ratio** | How aggressively the session should be reduced during compaction. |
+| **Compaction Model** | The model used to summarize old session context. |

-When enabled, compaction runs periodically as part of the bot's memory maintenance cycle.
+When enabled, Memoh can compact context in the background after a turn when the estimated input size passes the configured threshold.
+
+Memoh also uses the selected model's `context_window` to understand how close the session is to the available budget.

 ---

-## Manual Compaction
+## Immediate Compaction

-You can also trigger compaction manually from the bot's **Memory** tab:
+You can trigger compaction immediately for the current session in two ways:

-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**.
+### From The Session Status Panel
+
+1. Open the active conversation.
+2. Open the session status panel.
+3. Click **Compact Now**.
+
+The status panel also shows the current context usage, cache hit rate, and used skills, which helps you decide whether compaction is useful right now.
+
+### From Slash Commands
+
+Run:
+
+```text
+/compact
+```
+
+or:
+
+```text
+/compact run
+```
+
+This runs synchronous context compaction for the current session and returns a status result to chat.

 ---

-## Compaction Logs
+## Status And Logs

-The **Compaction** tab in the Bot Detail page provides an audit trail of all compaction runs:
+The **Compaction** tab in the bot detail page provides an audit trail for context 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.).
+Typical fields include:

-### Managing Logs
+- **Status** — whether the compaction finished successfully or failed
+- **Summary** — the compacted summary text or a summary preview
+- **Message Count** — how many messages were involved
+- **Started / Completed Time** — when the run happened
+- **Model / Usage** — metadata about the model and token usage when available

- **Refresh** — Reload the log list.
- **Clear Logs** — Remove old compaction records.
+The log list is useful when you want to verify that automatic compaction is actually running or diagnose a failure.

 ---

-## Relationship to Memory
+## Relationship To `context_window`

-Compaction works with whatever **Memory Provider** is assigned to the bot. The compaction process:
+Memoh tracks the current session against the selected chat model's `context_window`.

-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.
+You can see this in:

-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.
+- the Web UI session status panel
+- the `/status` slash command
+
+Compaction becomes more valuable as the active session gets closer to the model's context limit. A dedicated compaction model can also be used to summarize more cheaply than the main chat model.
+
+---
+
+## Context Compaction vs Memory Compaction
+
+These two features sound similar but solve different problems:
+
+| Feature | Scope | Trigger | Result |
+|---------|-------|---------|--------|
+| **Context Compaction** | One active session | Session panel or `/compact` | Summarizes older chat history for future turns |
+| **Memory Compaction** | Long-term memory provider | Memory tab | Rewrites stored memory entries |
+
+Use **Context Compaction** when one conversation has become too large.
+
+Use **Memory Compaction** when the bot's stored memories themselves have become noisy or redundant.

 ---

 ## Next Steps

- To manage individual memories, see [Memory Management](/getting-started/memory).
- To configure the memory backend, see [Memory Providers](/memory-providers/index).
+- To inspect session runtime information, see [Sessions](/getting-started/sessions).
+- To understand slash-triggered compaction, see [Slash Commands](/getting-started/slash-commands).
+- To manage long-term memory instead of session context, see [Bot Memory Management](/getting-started/memory).
@@ -6,6 +6,8 @@ Memoh fully supports the **Model Context Protocol (MCP)**, allowing you to conne

 MCP provides a standardized way for bots to access external data sources and tools. Each Bot can have its own independent set of MCP connections.

+You can configure connections manually from the **MCP** tab, or start from a curated template in **[Supermarket](/getting-started/supermarket.md)** and then review the prefilled draft in the bot editor.
+
 ---

 ## Connection Types
@@ -19,6 +19,8 @@ Without a memory provider, the bot will not have an active memory backend config

 Memories are stored and retrieved through the assigned memory provider. Depending on the provider type and mode, retrieval may use file-based indexing, sparse vectors, dense embeddings, or an external API. When a user sends a message, Memoh finds the most relevant memories and includes them in the bot's runtime context.

+This page is about **long-term memory**. It is separate from **session context compaction**, which reduces the prompt footprint of a single conversation session. See [Context Compaction](/getting-started/compaction).
+
 ---

 ## Operations
@@ -38,14 +40,22 @@ Manage your bot's memories from the **Memory** tab in the Bot Detail page.

 ---

-## Memory Compression (Compact)
+## Memory Compaction

-Over time, memories can accumulate and become redundant. The **Compact** feature helps optimize the memory pool.
+Over time, long-term memories can accumulate and become redundant. The **Compact** action in the **Memory** tab rewrites the stored memory set itself.

- **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.
+This operation is provider-level memory maintenance. It is useful when you want to:

-For more details on compaction, see [Memory Compaction](/getting-started/compaction).
+- merge overlapping memories
+- remove stale or low-value entries
+- improve retrieval quality by reducing noise
+
+Parameters:
+
+- **Ratio** — Compression ratio such as `0.8`, `0.5`, or `0.3`. Lower values make compaction more aggressive.
+- **Decay Days** — Optionally restrict compaction to older memories only.
+
+This is different from [Context Compaction](/getting-started/compaction), which compresses the active prompt for one session rather than rewriting stored memories.

 ---

@@ -81,6 +91,21 @@ The Memory tab displays storage usage information:

 ---

+## Memory vs Session Context
+
+Memoh has two different "compaction" concepts:
+
+| Concept | Scope | Where to trigger it | What it changes |
+|--------|-------|---------------------|-----------------|
+| **Memory Compaction** | Long-term memory provider | Memory tab | Rewrites stored memory entries |
+| **Context Compaction** | One conversation session | Session status panel or `/compact` | Summarizes older session context for future model calls |
+
+If you are trying to reduce retrieval noise across many conversations, use **Memory Compaction**.
+
+If you are trying to shorten the currently active conversation history, use **Context Compaction**.
+
+---
+
 ## Bot Interaction

 - The bot automatically searches and retrieves memories during chat.
@@ -1,78 +1,195 @@
-# LLM Provider and Model
+# Providers And Models

-To use Memoh, you first need to configure at least one LLM Provider and at least one Model. 
+To use Memoh effectively, you usually configure:

-## LLM Provider
+- one or more **providers** that define how Memoh talks to upstream APIs
+- one or more **models** under those providers
+- optional **speech providers** if you want text-to-speech

-An LLM Provider represents a connection to an AI service (like OpenAI, Anthropic, or a self-hosted compatible API). It stores the base URL and authentication credentials.
-
-### Creating a Provider
-
-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").
-    - **Base URL**: The root URL of the API (e.g., `https://api.openai.com/v1`).
-    - **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.
+The Web UI manages chat and embedding providers/models from the **Models** page. Speech models are managed separately from [TTS Providers](/tts-providers/index.md).

 ---

-## Model
+## Provider Basics

-A Model is a specific AI instance (like `gpt-4o` or `text-embedding-3-small`) that belongs to a Provider. Memoh distinguishes between **Chat** models (for conversation) and **Embedding** models (for memory search).
+A **provider** stores connection information for one upstream service, such as:

-### Adding a Model
+- the API protocol (`client_type`)
+- the base URL if the protocol needs one
+- credentials such as an API key or OAuth token

-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:
+Typical examples include OpenAI-compatible endpoints, Anthropic, Google Gemini, OpenAI Codex, and GitHub Copilot.

-| Field | Required | Description |
-|-------|----------|-------------|
-| **Type** | Yes | `chat` for conversation, `embedding` for vector search. |
-| **Model ID** | Yes | The exact identifier used by the provider (e.g., `gpt-4o`). |
-| **Name** | No | A friendly display name (defaults to Model ID). |
-| **Client Type** | Yes (Chat) | The API protocol: `openai-responses`, `openai-completions`, `anthropic-messages`, or `google-generative-ai`. |
-| **Input Modalities**| Yes (Chat) | Capabilities supported: `text` (default), `image`, `audio`, `video`, `file`. |
-| **Supports Reasoning**| No | Enable if the model supports internal reasoning steps (e.g., OpenAI o1). |
-| **Dimensions** | Yes (Embed) | The vector size for embedding models (e.g., 1536). |
+### Creating A Provider

-4. Click **Create**.
+1. Open the **Models** page from the settings sidebar.
+2. Click **Add Provider**.
+3. Fill in the provider form.
+4. Save the provider.

-### Managing Models
+Common fields:

- **Edit**: Click the edit icon next to a model in the list.
- **Delete**: Click the trash icon next to a model to remove it.
+| Field | Description |
+|-------|-------------|
+| **Name** | Friendly display name, such as `OpenAI` or `Copilot`. |
+| **Client Type** | API protocol used by this provider. |
+| **Base URL** | Root API endpoint, when required by the selected client type. |
+| **API Key** | Token-based authentication, when the client type uses direct credentials. |
+
+### Client Types
+
+Memoh currently supports these client types:
+
+| Client Type | Typical Use |
+|-------------|-------------|
+| `openai-responses` | OpenAI Responses API style providers |
+| `openai-completions` | OpenAI Chat Completions compatible providers |
+| `anthropic-messages` | Anthropic Messages API |
+| `google-generative-ai` | Google Gemini API |
+| `openai-codex` | OpenAI Codex / ChatGPT-backed coding workflow with OAuth |
+| `github-copilot` | GitHub Copilot with device OAuth |
+| `edge-speech` | Speech-only provider type for Microsoft Edge Read Aloud |
+
+`edge-speech` is for speech synthesis, not for chat. Configure it through [TTS Providers](/tts-providers/index.md), not as your main chat provider.
+
+---
+
+## OAuth-Based Providers
+
+Most provider types use a normal API key. Two notable exceptions are `openai-codex` and `github-copilot`.
+
+### OpenAI Codex
+
+- Uses the `openai-codex` client type
+- Authenticates through the provider form's OAuth flow instead of a normal API key workflow
+- The bundled preset points at `https://chatgpt.com/backend-api`
+
+This is a good fit when you want Codex-style model access for coding-oriented workflows.
+
+### GitHub Copilot
+
+- Uses the `github-copilot` client type
+- Uses **device authorization**
+- The provider form shows a verification URL and a user code while authorization is pending
+- After authorization completes, the provider stores the linked GitHub account token
+
+GitHub Copilot is especially useful if you already have access to Copilot-backed chat and embedding models and want to reuse that access from Memoh.
+
+---
+
+## Importing Models
+
+After creating a provider, you can import or add models under it.
+
+Typical flow:
+
+1. Select the provider.
+2. Click **Import Models** if the provider can expose a model catalog.
+3. Choose the models you want to save into Memoh.
+
+You can also add models manually when you already know the upstream model ID.
+
+---
+
+## Model Types
+
+Memoh distinguishes three model types:
+
+| Type | Purpose |
+|------|---------|
+| `chat` | Main LLMs for conversation, tool use, reasoning, and image generation |
+| `embedding` | Vector models for memory and retrieval |
+| `speech` | Text-to-speech models used by TTS providers |
+
+Important distinction:
+
+- The **Models** page is primarily where you manage `chat` and `embedding` models.
+- `speech` models are exposed through [TTS Providers](/tts-providers/index.md).
+
+---
+
+## Chat Model Configuration
+
+When adding a chat model, the most important fields are:
+
+| Field | Description |
+|-------|-------------|
+| **Model ID** | Exact upstream identifier, such as `gpt-4o` or `claude-sonnet-4.6`. |
+| **Name** | Friendly display name shown in the UI. |
+| **Compatibilities** | Feature flags such as `vision`, `tool-call`, `image-output`, and `reasoning`. |
+| **Context Window** | Approximate maximum context budget for the model. |
+
+### Compatibilities
+
+Memoh uses compatibility flags to decide which features a model can safely power:
+
+| Compatibility | Meaning |
+|---------------|---------|
+| `vision` | Model can accept images as input |
+| `tool-call` | Model can call tools |
+| `image-output` | Model can generate images |
+| `reasoning` | Model exposes explicit reasoning modes / effort levels |
+
+If a model supports reasoning, it may also declare `reasoning_efforts` such as `none`, `low`, `medium`, `high`, or `xhigh`.
+
+### `context_window`
+
+`context_window` is important because Memoh uses it to:
+
+- calculate session context usage in the Web UI
+- power `/status` output
+- decide when a session is approaching its prompt limit
+- guide [Context Compaction](/getting-started/compaction)
+
+If you leave `context_window` empty, the model can still be used, but Memoh cannot show an exact usage percentage for that model.
+
+### Image Generation Models
+
+Memoh now lets you assign an **Image Generation Model** to a bot. This model must be a chat model whose compatibilities include `image-output`.
+
+That keeps image generation separate from your default chat model when needed.
+
+---
+
+## Embedding Models
+
+Embedding models are used for semantic indexing and retrieval.
+
+The required field is:
+
+| Field | Description |
+|-------|-------------|
+| **Dimensions** | Vector size for the embedding output, such as `1536`. |
+
+Use embedding models with memory providers or any feature that relies on vector search.
+
+---
+
+## Speech Models
+
+Speech models are managed from [TTS Providers](/tts-providers/index.md), not from the standard chat provider flow.
+
+Current built-in example:
+
+- **Edge TTS** via `edge-speech`
+
+This separation matters because speech models have voice, format, speed, and pitch settings that do not apply to chat or embedding models.
+
+---
+
+## Recommended Mental Model
+
+For most bots, think in terms of three parallel model roles:
+
+- **Chat model** for normal conversations
+- **Embedding model** for memory search
+- **Speech / image models** for side capabilities such as TTS and image generation
+
+You do not need to force one model to do everything.

 ---

 ## Next Steps

-Now that you have configured your models, you can proceed to [Create and Configure a Bot](/getting-started/bot).
+- To assign chat, image, browser, memory, and TTS settings to a bot, see [Bot Management](/getting-started/bot).
+- To configure speech providers and speech models, see [TTS Providers](/tts-providers/index.md).
@@ -14,28 +14,64 @@ Sessions are scoped per bot — each bot manages its own set of sessions indepen

 ## Session Types

-Memoh uses four session types to separate different kinds of bot activity:
+Memoh uses five 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. |
+| **Discuss** | Observation-oriented conversation mode. The bot may stay silent by default and only speaks when it decides to send a real reply into the conversation. |
 | **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.
+Only **Chat** and **Discuss** sessions are directly created from user conversation routes. The other session types are system-managed and appear as read-only records in the session list.
+
+### Chat vs Discuss
+
+`chat` and `discuss` are the two session types you are most likely to see in normal conversation threads.
+
+**Chat** means:
+
+- the conversation behaves like a normal direct assistant exchange
+- users expect a visible reply when they send a prompt
+- this is the default in the Web UI and in direct-message style conversations
+
+**Discuss** means:
+
+- the bot is observing an ongoing conversation, often in a group
+- the model's direct text output is treated as internal monologue
+- the bot only speaks to the conversation when it explicitly issues a `send` action
+- staying silent is valid and often desirable
+
+In practice, `discuss` is what makes Memoh feel less like a synchronous chatbot and more like a participant that can decide whether to join in.

 ---

 ## Starting a New Session with `/new`

-The `/new` slash command creates a fresh chat session, resetting the conversation context. This works across all channels:
+The `/new` slash command creates a fresh session on the current conversation route, resetting the active session context without deleting old history.
+
+Supported forms:
+
+- `/new` — create a new session using the default session type for the current context
+- `/new chat` — force a normal chat session
+- `/new discuss` — force a discuss session
+
+Default routing behavior:
+
+- **Web UI local chat** defaults to `chat`
+- **private conversations** default to `chat`
+- **group conversations on channel adapters** default to `discuss`
+
+`/new discuss` is not supported from the built-in Web UI local channel. Use a real channel adapter such as Telegram, Discord, or Misskey if you want to explicitly create discuss sessions.
+
+This works across supported channels:

 ### In External Channels (Telegram, Discord, Feishu, etc.)

-Send `/new` as a message to the bot. The bot will:
+Send `/new`, `/new chat`, or `/new discuss` as a message to the bot. The bot will:

-1. Create a new chat session.
+1. Create a new session of the requested or inferred type.
 2. Route all subsequent messages from you to this new session.
 3. The previous session's history is preserved but no longer active.

@@ -52,7 +88,7 @@ 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).
+- Filter sessions by type (`chat`, `discuss`, `heartbeat`, `schedule`, `subagent`).
 - Rename or delete sessions.

 ---
@@ -67,6 +103,8 @@ In the Web UI, the session sidebar lists all sessions for the currently selected
 - **Type** — The session type icon.
 - **Last Activity** — When the session was last active.

+For everyday chat use, `chat` and `discuss` sessions are intentionally shown together because they both represent user-facing conversation threads.
+
 ### Renaming Sessions

 Click on a session title to rename it. This helps organize conversations by topic.
@@ -77,8 +115,25 @@ Remove sessions you no longer need. Deleting a session removes its message histo

 ---

+## Session Status Panel
+
+The session status panel provides a compact runtime summary for the active session. It is the same information surfaced by `/status`.
+
+Key fields include:
+
+- **Messages** — total message count in the session
+- **Context Usage** — current used tokens relative to the selected model's `context_window`
+- **Cache Hit Rate** — how much of the input came from cache reads
+- **Cache Read / Cache Write** — token counts associated with caching
+- **Skills** — effective skills used by the session
+
+The panel also exposes **Compact Now**, which triggers immediate [Context Compaction](/getting-started/compaction) for the current session.
+
+---
+
 ## How Sessions Relate to Other Features

+- **Discuss** sessions are optimized for channels where the bot should observe and selectively speak, especially in group conversations.
 - **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.
@@ -1,46 +1,147 @@
 # Bot Skills

-Skills are the "personality" and "capabilities" of a Memoh Bot. They define how the bot should behave and what tools it can use.
+Skills are reusable prompt modules that extend a bot's behavior, style, and tool-usage guidance. You manage them from the bot's **Skills** tab, and you can either write them yourself or install them from **[Supermarket](/getting-started/supermarket.md)**.

-## Concept: Skills as Markdown
+---

-A **Skill** is represented as a Markdown document with YAML frontmatter. These files are stored within the bot's container and parsed into tools and personality traits.
+## What A Skill Looks Like

-### Example Skill Structure
+A skill is a Markdown file named `SKILL.md` with YAML frontmatter. At minimum, give it a stable `name` and a short `description`.

 ```yaml
 ---
 name: coder-skill
-description: Enables advanced coding capabilities and tool use.
+description: Enables advanced coding workflows and tool usage.
 ---

 # Coder Skill
-As a coder, you always follow best practices and write clean, documented code. 
-You can use the `edit_file` and `run_command` tools to assist the user.
+
+You write clear code, explain trade-offs, and use file or command tools when they help complete the task.
 ```

+Practical rules:
+
+- Use a simple ASCII skill name such as `coder-skill`, `research`, or `docs-helper`.
+- Avoid spaces in the `name`; Memoh uses it as the skill directory name.
+- The Markdown body is the actual instruction content injected into the bot runtime.
+
 ---

-## Managing Skills
+## Where Skills Come From

-Manage your bot's skill set from the **Skills** tab in the Bot Detail page.
+Memoh distinguishes between **managed** skills and **discovered** skills:

-### Adding a Skill
+- **Managed** skills are the ones you create, edit, or install through Memoh. They live under `/data/skills/<name>/SKILL.md`.
+- **Discovered** skills are found from compatibility locations inside the bot environment, such as legacy skill directories from imported images or older setups.
+
+Memoh scans these container-internal roots in order:
+
+| Type | Root |
+|------|------|
+| Managed | `/data/skills/` |
+| Legacy discovered | `/data/.skills/` |
+| Compatibility discovered | `/data/.agents/skills/` |
+| Compatibility discovered | `/root/.agents/skills/` |
+
+Within each root, Memoh looks for `SKILL.md` either directly under the root or inside a named subdirectory such as `/data/skills/coder-skill/SKILL.md`.
+
+This matters because the same skill name can appear from multiple sources. Memoh resolves those duplicates into states.
+
+---
+
+## Skill States
+
+Each listed skill source has one of these states:
+
+| State | Meaning |
+|-------|---------|
+| `effective` | This is the version currently active for that skill name |
+| `shadowed` | Another source with the same skill name takes precedence |
+| `disabled` | This specific source has been disabled and will not be used |
+
+The important mental model is: **the skill name is the identity**. If Memoh finds multiple `coder-skill` sources, only one can be `effective`.
+
+### Typical Examples
+
+- A skill you just created in Memoh is usually `managed` + `effective`.
+- A legacy skill can show up as `effective` until you create or adopt a managed skill with the same name.
+- After you adopt a discovered skill into the managed directory, the managed copy becomes `effective` and the old source usually becomes `shadowed`.
+- If you disable the effective source, another source with the same name may become `effective` automatically.
+
+---
+
+## Managing Skills In The UI
+
+Open a bot, then go to **Skills**.
+
+### Add Skill

 1. Click **Add Skill**.
-2. A dialog with a basic template will open in the **Monaco Editor**.
-3. Fill in the `name`, `description`, and content.
-4. Click **Save**.
+2. Fill in the raw Markdown in the editor.
+3. Save it.

-### Editing and Deleting
+Memoh writes the file into its managed skills directory.

- **Edit**: Click the pencil icon next to a skill card to modify its content or frontmatter.
- **Delete**: Click the trash icon to remove a skill from the bot's container.
+### Edit Skill
+
+- Use **Edit** on a card to update the raw `SKILL.md` content.
+- Editing is most useful for managed skills you own directly in Memoh.
+
+### Delete Skill
+
+- **Delete** removes the managed skill directory for that skill name.
+- Deleting a managed skill can expose a discovered fallback source with the same name, making that fallback become `effective`.
+
+### Disable / Enable
+
+- **Disable** turns off one specific skill source without deleting it.
+- **Enable** re-enables a previously disabled source.
+
+Use this when you want to test a fallback or temporarily remove a skill from the prompt without losing its content.
+
+### Adopt
+
+**Adopt** copies a discovered skill into Memoh's managed skills directory so you can own and edit it from the UI.
+
+Use adopt when:
+
+- a skill came from a legacy or compatibility source
+- you want that skill to become part of your Memoh-managed configuration
+- you want to edit it safely in the UI later
+
+Adopt is not available once a managed skill with the same name already exists.

 ---

-## How Bots Use Skills
+## Effective Skills At Runtime

- Skills are injected into the bot's system prompt during conversation.
- The YAML frontmatter helps the system categorize and manage the skills as tools.
- Modular skills allow you to easily "swap" behaviors or capabilities without rewriting the entire bot.
+Only **effective** skills are loaded into the bot runtime.
+
+That means:
+
+- `shadowed` skills are visible for inspection, but not used
+- `disabled` skills are ignored
+- the active prompt only sees the current effective set
+
+In active sessions, the **Session Status Panel** can also show which skills were used during that session.
+
+---
+
+## Supermarket And Imported Skills
+
+Two common ways skills appear without being typed manually:
+
+- **Supermarket install**: Memoh downloads the selected skill into the managed skills directory, so it behaves like a normal managed skill.
+- **Imported / legacy environment**: Memoh discovers existing skills from compatibility paths and shows them as discovered sources.
+
+If a discovered skill is useful but you want to fully manage it in Memoh, adopt it.
+
+---
+
+## Recommended Workflow
+
+1. Start with a small number of focused skills.
+2. Prefer clear names and short descriptions.
+3. Use **Disable** before **Delete** if you are unsure.
+4. Use **Adopt** for legacy skills you plan to keep.
+5. Install reusable skills from **[Supermarket](/getting-started/supermarket.md)** instead of copy-pasting them repeatedly.
@@ -1,72 +1,341 @@
 # 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.
+Memoh bots support **slash commands** that are intercepted before the LLM runs. They are intended for fast inspection and control tasks such as viewing settings, switching providers, checking session status, or creating a fresh session.

-Slash commands are intercepted before they reach the LLM, so they execute instantly and don't consume tokens.
+Slash commands work in channel adapters and in the built-in Web UI chat. They do not consume model tokens just to parse the command itself.

 ---

-## Quick Reference
+## Command Model

-| 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 |
+Most commands follow a resource-group pattern:

---
-
-## Command Format
-
-Commands follow the pattern:
-
-```
+```text
 /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.
+Examples:

-Example: `/schedule create daily-report "0 9 * * *" "Send me a daily summary"`
+```text
+/schedule list
+/model current
+/schedule create morning-news "0 9 * * *" "Send a daily summary"
+```
+
+Key ideas:
+
+- **resource** is the command group, such as `schedule`, `model`, or `status`.
+- **action** is the specific operation, such as `list`, `get`, `set`, or `latest`.
+- **arguments** are positional values after the action. Use quotes when a value contains spaces.
+- Some groups have a **default action**, so `/settings` is equivalent to `/settings get`, and `/status` is equivalent to `/status show`.
+
+Two commands are **top-level** instead of resource groups:
+
+- `/new` — create a new session for the current conversation route
+- `/stop` — abort the currently running generation for the current conversation
+
+---
+
+## Built-in Help
+
+The slash system has layered help built into it:
+
+| Command | Meaning |
+|---------|---------|
+| `/help` | Show the top-level command list |
+| `/help <group>` | Show actions inside one group |
+| `/help <group> <action>` | Show detailed usage for one action |
+
+Examples:
+
+```text
+/help
+/help model
+/help model set
+```
+
+This is the fastest way to discover the exact live command surface for your current Memoh version.
+
+---
+
+## Parsing Rules
+
+Slash commands support a few convenience forms:
+
+- **Mention-prefixed commands** work in group chats, for example `@BotName /help`.
+- **Telegram bot suffixes** are accepted, for example `/help@MemohBot`.
+- Quoted strings are preserved as one argument, for example:
+
+```text
+/schedule create morning-news "0 9 * * *" "Send today's top stories"
+```
+
+If the text does not resolve to a known command, Memoh treats it as a normal chat message instead of a slash command.

 ---

 ## 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.
+Read-only actions are available to users who can already chat with the bot. Write actions such as `set`, `create`, `update`, `delete`, `enable`, and `disable` are **owner-only**.

-Owner-only commands are marked with `[owner]` in the `/help` output.
+In `/help` output, owner-only actions are marked with `[owner]`.

 ---

-## Global Commands
+## Quick Reference

-### `/help`
+### Top-Level Commands

-Displays a list of all available commands and their usage.
+| Command | Description |
+|---------|-------------|
+| `/help` | Show slash command help |
+| `/new [chat|discuss]` | Create a new session for the current route |
+| `/stop` | Stop the current generation |
+
+### Resource Groups
+
+| Group | Description | Default Action |
+|-------|-------------|----------------|
+| `/schedule` | Manage scheduled tasks | None |
+| `/mcp` | Inspect MCP connections | None |
+| `/settings` | View and update bot settings | `get` |
+| `/model` | View and switch bot models | None |
+| `/memory` | View and switch memory providers | None |
+| `/search` | View and switch search providers | None |
+| `/browser` | View and switch browser contexts | None |
+| `/usage` | View token usage | `summary` |
+| `/email` | Inspect email providers, bindings, and outbox | None |
+| `/heartbeat` | View recent heartbeat logs | `logs` |
+| `/skill` | View loaded bot skills | `list` |
+| `/fs` | Browse files inside the bot container | None |
+| `/status` | Inspect session message/context/cache status | `show` |
+| `/access` | Inspect identity, role, and ACL context | `show` |
+| `/compact` | Trigger immediate session context compaction | `run` |
+
+---
+
+## Session Commands

 ### `/new`

-Starts a new conversation session, resetting the current context. See [Sessions](/getting-started/sessions) for details.
+Creates a fresh session for the current conversation route. It is the fastest way to reset conversational context without deleting old history.
+
+Supported forms:
+
+- `/new` — use the default session type for the current context
+- `/new chat` — force a normal chat session
+- `/new discuss` — force a discuss session
+
+Default behavior:
+
+- **Web UI local chat** defaults to `chat`
+- **Direct messages** default to `chat`
+- **Group conversations on channel adapters** default to `discuss`
+
+`/new discuss` is not supported in the built-in Web UI local channel. Use a channel adapter such as Telegram or Discord if you want explicit discuss sessions.
+
+See [Sessions](/getting-started/sessions) for how `chat` and `discuss` differ.
+
+### `/stop`
+
+Stops the current in-progress generation for the current conversation. This is useful when:
+
+- the bot is still streaming and you already have what you need
+- a tool loop is taking too long
+- you want to interrupt the current turn before sending a follow-up

 ---

-## `/schedule` — Manage Scheduled Tasks
+## Status And Inspection Commands

-| Sub-command | Usage | Permission |
-|-------------|-------|------------|
+### `/status`
+
+Shows session-level runtime stats for the current conversation:
+
+- message count
+- current context usage
+- cache hit rate
+- cache read/write tokens
+- used skills in the session
+
+Actions:
+
+| Action | Usage |
+|--------|-------|
+| `show` | `/status` or `/status show` |
+| `latest` | `/status latest` |
+
+Use `show` for the currently active conversation route. Use `latest` when you want the newest session for the bot even if the current route has no active session.
+
+### `/access`
+
+Shows the current identity and permission context that Memoh is using for the command:
+
+- channel identity
+- linked user
+- bot role
+- whether write commands are allowed
+- channel / conversation / thread scope
+- evaluated chat ACL result
+
+Usage:
+
+```text
+/access
+```
+
+This command is useful when debugging ACL rules, linked accounts, or why a write command was denied.
+
+### `/usage`
+
+Shows token usage for the last 7 days.
+
+Actions:
+
+| Action | Usage |
+|--------|-------|
+| `summary` | `/usage` or `/usage summary` |
+| `by-model` | `/usage by-model` |
+
+### `/heartbeat`
+
+Shows the most recent heartbeat execution logs.
+
+Actions:
+
+| Action | Usage |
+|--------|-------|
+| `logs` | `/heartbeat` or `/heartbeat logs` |
+
+### `/email`
+
+Shows email-related configuration data for the current bot.
+
+Actions:
+
+| Action | Usage |
+|--------|-------|
+| `providers` | `/email providers` |
+| `bindings` | `/email bindings` |
+| `outbox` | `/email outbox` |
+
+---
+
+## Configuration Commands
+
+### `/settings`
+
+Shows or updates core bot settings.
+
+Actions:
+
+| Action | Usage | Permission |
+|--------|-------|------------|
+| `get` | `/settings` or `/settings get` | All |
+| `update` | `/settings update [options]` | Owner |
+
+Supported `update` options:
+
+| Option | Description |
+|--------|-------------|
+| `--language` | Bot language, such as `en` or `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 |
+| `--chat_model_id` | Chat model UUID |
+| `--heartbeat_model_id` | Heartbeat model UUID |
+
+Example:
+
+```text
+/settings update --language en --heartbeat_enabled true --heartbeat_interval 30
+```
+
+### `/model`
+
+Shows or switches the bot's chat and heartbeat models.
+
+Actions:
+
+| Action | Usage | Permission |
+|--------|-------|------------|
+| `list [provider_name]` | `/model list` | All |
+| `current` | `/model current` | All |
+| `set` | `/model set <model_id>` or `/model set <provider_name> <model_name>` | Owner |
+| `set-heartbeat` | `/model set-heartbeat <model_id>` or `/model set-heartbeat <provider_name> <model_name>` | Owner |
+
+Examples:
+
+```text
+/model list
+/model list OpenAI
+/model current
+/model set gpt-4o
+/model set OpenAI gpt-4o
+```
+
+### `/memory`
+
+Shows or switches the active memory provider.
+
+Actions:
+
+| Action | Usage | Permission |
+|--------|-------|------------|
+| `list` | `/memory list` | All |
+| `current` | `/memory current` | All |
+| `set` | `/memory set <name>` | Owner |
+
+### `/search`
+
+Shows or switches the active search provider.
+
+Actions:
+
+| Action | Usage | Permission |
+|--------|-------|------------|
+| `list` | `/search list` | All |
+| `current` | `/search current` | All |
+| `set` | `/search set <name>` | Owner |
+
+### `/browser`
+
+Shows or switches the active browser context.
+
+Actions:
+
+| Action | Usage | Permission |
+|--------|-------|------------|
+| `list` | `/browser list` | All |
+| `current` | `/browser current` | All |
+| `set` | `/browser set <name>` | Owner |
+
+### `/mcp`
+
+Shows or deletes MCP connections configured for the bot.
+
+Actions:
+
+| Action | Usage | Permission |
+|--------|-------|------------|
+| `list` | `/mcp list` | All |
+| `get` | `/mcp get <name>` | All |
+| `delete` | `/mcp delete <name>` | Owner |
+
+---
+
+## Automation And Filesystem Commands
+
+### `/schedule`
+
+Manages scheduled tasks for the bot.
+
+Actions:
+
+| Action | Usage | Permission |
+|--------|-------|------------|
 | `list` | `/schedule list` | All |
 | `get` | `/schedule get <name>` | All |
 | `create` | `/schedule create <name> <pattern> <command>` | Owner |
@@ -75,164 +344,60 @@ Starts a new conversation session, resetting the current context. See [Sessions]
 | `enable` | `/schedule enable <name>` | Owner |
 | `disable` | `/schedule disable <name>` | Owner |

-**Examples:**
+Examples:

-```
+```text
 /schedule list
 /schedule create morning-news "0 9 * * *" "Summarize today's top tech news"
 /schedule disable morning-news
 ```

---
+### `/skill`

-## `/mcp` — Manage MCP Connections
+Lists the currently available bot skills.

-| Sub-command | Usage | Permission |
-|-------------|-------|------------|
-| `list` | `/mcp list` | All |
-| `get` | `/mcp get <name>` | All |
-| `delete` | `/mcp delete <name>` | Owner |
+Actions:

---
+| Action | Usage |
+|--------|-------|
+| `list` | `/skill` or `/skill list` |

-## `/settings` — View and Update Bot Settings
+### `/fs`

-| Sub-command | Usage | Permission |
-|-------------|-------|------------|
-| `get` | `/settings` or `/settings get` | All |
-| `update` | `/settings update [options]` | Owner |
+Browses the bot container filesystem.

-**Update options:**
+Actions:

-| 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 |
+| Action | Usage |
+|--------|-------|
+| `list` | `/fs list [path]` |
+| `read` | `/fs read <path>` |

-**Example:**
+Examples:

-```
-/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 <provider_name> <model_name>` | Owner |
-| `set-heartbeat` | `/model set-heartbeat <provider_name> <model_name>` | 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 <name>` | Owner |
-
---
-
-## `/search` — Manage Search Provider
-
-| Sub-command | Usage | Permission |
-|-------------|-------|------------|
-| `list` | `/search list` | All |
-| `set` | `/search set <name>` | Owner |
-
---
-
-## `/browser` — Manage Browser Context
-
-| Sub-command | Usage | Permission |
-|-------------|-------|------------|
-| `list` | `/browser list` | All |
-| `set` | `/browser set <name>` | 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 <path>` | All |
-
-**Examples:**
-
-```
+```text
 /fs list /
 /fs list /home
 /fs read /home/bot/IDENTITY.md
 ```

-File content is truncated to 2000 characters when displayed in chat.
+Read output is truncated when the file is very large.

 ---

-## Mention-Prefixed Commands
+## Context Compaction Command

-In group chats, you can prefix commands with a mention:
+### `/compact`

-```
-@BotName /help
-@BotName /new
-```
+Triggers immediate **session context compaction** for the current session. This is different from memory compaction:

-The bot will strip the mention and process the slash command normally.
+- **context compaction** reduces the active prompt/history footprint of one session
+- **memory compaction** rewrites long-term memory entries in the memory provider
+
+Actions:
+
+| Action | Usage |
+|--------|-------|
+| `run` | `/compact` or `/compact run` |
+
+Use this when the current conversation has grown long and you want Memoh to summarize older turns before continuing. See [Context Compaction](/getting-started/compaction).
@@ -0,0 +1,35 @@
+# Supermarket
+
+Supermarket is Memoh's built-in catalog for **skills** and **MCP templates**.
+
+---
+
+## Install A Skill
+
+1. Open **Supermarket** in the Web UI.
+2. Switch to the **Skills** tab.
+3. Choose a skill and click **Install**.
+4. Select the target bot.
+5. Confirm the install.
+6. The skill appears in that bot's **Skills** tab.
+
+---
+
+## Install An MCP Template
+
+1. Open **Supermarket** in the Web UI.
+2. Switch to the **MCP** tab.
+3. Choose an entry and click **Install**.
+4. Select the target bot.
+5. Memoh opens that bot's **MCP** tab with a prefilled draft connection.
+6. Fill in any required secrets or OAuth details.
+7. Save the connection.
+8. Probe it if you want to refresh tool discovery.
+
+---
+
+## Contribute
+
+Contribute new skills or MCP templates here:
+
+- [memohai/supermarket](https://github.com/memohai/supermarket)
@@ -1,10 +1,26 @@
 # 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, 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.
+Memoh(/ˈmemoʊ/) is a multi-member, structured long-memory, containerized AI agent platform. Create bots with isolated workspaces, persistent memory, tool access, and channel integrations across Telegram, Discord, Lark (Feishu), QQ, Matrix, Misskey, DingTalk, WeCom, WeChat, WeChat Official Account, Email, and Web.

-## Documentation
+## Start Here

- **[About Memoh](/about)** — What Memoh is, key features, and installation links.
- **[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, Discord, QQ, Matrix, WeCom, and WeChat.
+- **[About Memoh](/about)** — Product overview, platform model, and where to begin.
+- **[Docker Installation](/installation/docker)** — Recommended deployment path.
+- **[Providers And Models](/getting-started/provider-and-model)** — Set up providers, client types, and model roles.
+- **[Bot Setup](/getting-started/bot)** — Create a bot and configure its main tabs.
+- **[Sessions](/getting-started/sessions)** — Understand chat vs discuss sessions, status panels, and routing.
+- **[Slash Commands](/getting-started/slash-commands)** — Learn the command model and daily control surface.
+
+## Feature Guides
+
+- **[Channels](/getting-started/channels)** — Platform overview and links to per-channel guides.
+- **[Access Control](/getting-started/access)** — ACL presets, rule ordering, and scoped access.
+- **[Skills](/getting-started/skills)** — Managed skills, effective/shadowed states, and adoption workflow.
+- **[Supermarket](/getting-started/supermarket)** — Install skills and MCP templates from the catalog.
+- **[MCP](/getting-started/mcp)** — Configure tool servers, OAuth, probing, import/export.
+- **[Memory](/getting-started/memory)** — Long-term memory providers and memory compaction.
+- **[Context Compaction](/getting-started/compaction)** — Reduce active session context size without changing stored memory.
+
+## Chinese Entry
+
+- **[简体中文入口](/zh/)** — Chinese landing page with translated concepts and links to key guides.
@@ -1,22 +1,39 @@
-# Memoh 文档
+# Memoh 中文入口

-Memoh 是一个多成员、长记忆、容器化的 AI Agent 系统。
+Memoh 是一个多成员、长记忆、容器化的 AI Agent 平台。当前中文站点同时包含：

-## 文档章节
+- 已翻译的中文概念文档
+- 指向英文主文档的常用功能入口
+
+如果你是第一次接触 Memoh，建议先看英文主文档里的功能指南；如果你正在理解账号语义、绑定关系和访问控制，再看下面的中文概念页。
+
+## 常用功能入口
+
+- [产品概览（英文）](/about)
+- [Docker 安装（英文）](/installation/docker)
+- [Providers And Models（英文）](/getting-started/provider-and-model)
+- [Bot 配置（英文）](/getting-started/bot)
+- [Sessions / Discuss 模式（英文）](/getting-started/sessions)
+- [Channels 渠道接入（英文）](/getting-started/channels)
+- [Skills（英文）](/getting-started/skills)
+- [Supermarket（英文）](/getting-started/supermarket)
+- [Slash Commands（英文）](/getting-started/slash-commands)
+
+## 中文概念文档

- [快速开始](/getting-started.md)
 - [核心概念](/zh/concepts/index.md)
+- [账号模型与绑定](/zh/concepts/identity-and-binding.md)

-## 面向文档贡献者
+## 面向文档维护者

 - [术语规范](/zh/style/terminology.md)

-## 当前维护范围
+## 当前中文维护范围

-当前文档先聚焦账号语义与访问控制：
+当前中文内容优先覆盖账号语义与访问控制相关的概念：

 - 区分系统账号与平台账号
 - 解释为什么账号绑定是账号作用域
 - 说明账号绑定与 bot 访问控制之间的关系

-说明：“平台账号”指用户在外部平台上的真实账号（例如飞书账号），不是 Memoh 系统账号。
+说明：“平台账号”指用户在外部平台上的真实账号，例如飞书账号，而不是 Memoh 系统账号。