diff --git a/docs/docs/.vitepress/config.ts b/docs/docs/.vitepress/config.ts index e735f6c8..b38e3397 100644 --- a/docs/docs/.vitepress/config.ts +++ b/docs/docs/.vitepress/config.ts @@ -31,7 +31,7 @@ export default defineConfig({ link: '/index.md' }, { - text: 'Getting Started', + text: 'About Memoh', link: '/getting-started.md' }, { @@ -47,6 +47,15 @@ export default defineConfig({ } ] }, + { + text: 'Getting Started', + items: [ + { + text: 'Provider and Model', + link: '/getting-started/provider-and-model.md' + } + ] + }, { text: 'CLI', items: [ @@ -87,56 +96,12 @@ export default defineConfig({ link: '/cli/chat.md' } ] - }, - { - text: 'Core Concepts', - items: [ - { - text: 'Concepts Overview', - link: '/concepts/index.md' - }, - { - text: 'Accounts and Linking', - link: '/concepts/identity-and-binding.md' - } - ] - }, - { - text: 'Documentation Style Guide', - items: [ - { - text: 'Terminology Rules', - link: '/style/terminology.md' - } - ] } ], '/zh/': [ { text: '文档总览', link: '/zh/index.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' - } - ] } ] }, diff --git a/docs/docs/concepts/identity-and-binding.md b/docs/docs/concepts/identity-and-binding.md deleted file mode 100644 index bb7982b6..00000000 --- a/docs/docs/concepts/identity-and-binding.md +++ /dev/null @@ -1,41 +0,0 @@ -# Accounts and Linking - -## Account Model - -Memoh treats platform accounts and system accounts as two different entities: - -- **Platform Account (`ChannelIdentity`)** is the user's account on an external access platform (for example, a TG account), not a Memoh internal account. -- **System Account (`User`)** is an internal account in Memoh. - -A platform account can exist before linking. -`bind` is the mechanism that links these two account types. - -## Access Platform and Bot - -- **Access Platform (`channel`)** is where inbound messages come from. -- **Bot** is an authorization and resource boundary inside Memoh. - -Bots are managed by system accounts, while inbound messages are produced by platform accounts. - -## Why Linking Is Account-Scoped - -Account linking exists to establish account ownership, not to grant bot resources directly: - -- It links platform accounts and system accounts independent of any single bot. -- It avoids coupling account linking with member management semantics. -- It keeps bot authorization and account linking decoupled. - -## Linking Flow (Current Consensus) - -1. A user requests a bind code under their own system account. -2. The platform account sends the code from a supported access-platform conversation. -3. Memoh validates the code and links platform account to system account. -4. Bot membership and authorization are handled by their own flows. - -## Bot Type Semantics - -- **Public bot**: supports member-based collaboration. -- **Personal bot**: conceptually single-owner, and should not rely on member semantics. - -> Note: The conceptual model is documented here as product semantics. -> Runtime behavior may still be in transition as implementations are tightened. diff --git a/docs/docs/concepts/index.md b/docs/docs/concepts/index.md deleted file mode 100644 index e6d54718..00000000 --- a/docs/docs/concepts/index.md +++ /dev/null @@ -1,21 +0,0 @@ -# Core Concepts - -This section defines the core account and access concepts used by Memoh. - -## Concept Map - -- **System Account (`User`)**: an internal account in Memoh. -- **Platform Account (`ChannelIdentity`)**: a user's account on an external access platform, not a Memoh account (for example, the user's Telegram (TG) account). -- **Bot**: an access and resource boundary managed by a system account. -- **Account Linking (`bind`)**: the process that links a platform account to a system account. - -## Why This Matters - -Memoh receives messages from external access platforms, but manages permissions and resources inside the system. -To keep these concerns clear, the model separates platform accounts from system accounts, while keeping bot access control as an independent concern. - -Terminology note: "platform account" always means the user's account on that platform (such as TG), not an internal account created by this project. - -## In This Chapter - -- [Accounts and Linking](/concepts/identity-and-binding.md) diff --git a/docs/docs/getting-started.md b/docs/docs/getting-started.md index b1e9d291..19807dd1 100644 --- a/docs/docs/getting-started.md +++ b/docs/docs/getting-started.md @@ -1,4 +1,4 @@ -# Getting Started +# About Memoh ## What is Memoh? diff --git a/docs/docs/getting-started/provider-and-model.md b/docs/docs/getting-started/provider-and-model.md new file mode 100644 index 00000000..09b8c387 --- /dev/null +++ b/docs/docs/getting-started/provider-and-model.md @@ -0,0 +1,84 @@ +# Configure Provider and Model + +Before creating bots, you need to configure at least one LLM provider and add chat and embedding models. This guide walks you through the Web UI. + +## Prerequisites + +- Memoh is running (see [Docker installation](/installation/docker)) +- You have logged in to the Web UI at http://localhost:8082 + +## Step 1: Open the Models Page + +Click **Models** in the left sidebar to open the Provider and Model configuration page. + +![Models page - sidebar](/getting-started/provider-model-01-sidebar.png) + +The page has two panels: +- **Left**: Provider list and filter +- **Right**: Selected provider's details and models (or an empty state if none selected) + +## Step 2: Add a Provider + +Click the **Add Provider** button (with a plus icon) at the bottom of the left panel. + +![Add Provider button](/getting-started/provider-model-02-add-provider.png) + +In the dialog, fill in: + +| Field | Description | +|-------|-------------| +| **Name** | A display name for this provider (e.g. `my-openai`, `ollama-local`) | +| **API Key** | Your API key. For local services like Ollama, you can use a placeholder like `ollama` | +| **Base URL** | The API base URL (e.g. `https://api.openai.com/v1`, `http://localhost:11434/v1` for Ollama) | +| **Type** | Client type: `openai`, `openai-compat`, `anthropic`, `google`, `azure`, `bedrock`, `mistral`, `xai`, `ollama`, `dashscope` | + +![Add Provider dialog](/getting-started/provider-model-03-provider-dialog.png) + +**Example — OpenAI:** +- Name: `openai` +- API Key: `sk-...` +- Base URL: `https://api.openai.com/v1` +- Type: `openai` + +**Example — Ollama (local):** +- Name: `ollama` +- API Key: `ollama` +- Base URL: `http://localhost:11434/v1` +- Type: `ollama` + +Click **Add** to save. The new provider appears in the left sidebar. + +## Step 3: Add Models + +Select a provider from the left panel. The right panel shows the provider form and the model list. + +![Provider selected - model list](/getting-started/provider-model-04-provider-selected.png) + +Click **Add Model** to open the model creation dialog. + +Fill in: + +| Field | Description | +|-------|-------------| +| **Type** | `chat` or `embedding` | +| **Model** | Model ID (e.g. `gpt-4`, `llama3.2`, `text-embedding-3-small`) | +| **Display Name** | Optional display name | +| **Dimensions** | Required for embedding models (e.g. `1536` for OpenAI embeddings) | +| **Multimodal** | For chat models only — enable if the model supports images | + +**You need at least:** +- One **chat** model (for conversation) +- One **embedding** model (for memory) + +Add them under the same or different providers. For example: +- Chat: `gpt-4` (OpenAI) or `llama3.2` (Ollama) +- Embedding: `text-embedding-3-small` (OpenAI) or `nomic-embed-text` (Ollama) + +## Step 4: Edit or Delete + +- **Provider**: After selecting a provider, you can edit Name, API Key, and Base URL in the right panel, or delete the provider. +- **Model**: Use the edit or delete actions on each model card in the list. + +## Next Steps + +Once you have at least one chat model and one embedding model, you can create a bot (via **Bots** in the sidebar) and assign these models in the bot settings. diff --git a/docs/docs/index.md b/docs/docs/index.md index 8ee8bb5b..66e7294d 100644 --- a/docs/docs/index.md +++ b/docs/docs/index.md @@ -4,11 +4,7 @@ Memoh is a multi-member, structured long-memory, containerized AI agent system. ## Documentation -- **[Getting Started](/getting-started)** — What Memoh is, key features, and installation links. +- **[About Memoh](/getting-started)** — What Memoh is, key features, and installation links. - **[Installation](/installation/docker)** — [Docker](/installation/docker) (recommended) and [config.toml](/installation/config-toml) reference. +- **[Getting Started](/getting-started/provider-and-model)** — Configure provider and model. - **[CLI](/cli/)** — Command-line tool for bots, channels, providers, models, schedules, and chat. -- **[Core Concepts](/concepts/)** — [Concepts overview](/concepts/) and [Accounts and linking](/concepts/identity-and-binding). - -## For Contributors - -- [Terminology Rules](/style/terminology) — Documentation style guide. diff --git a/docs/docs/public/getting-started/provider-model-01-sidebar.png b/docs/docs/public/getting-started/provider-model-01-sidebar.png new file mode 100644 index 00000000..4365a3cf Binary files /dev/null and b/docs/docs/public/getting-started/provider-model-01-sidebar.png differ diff --git a/docs/docs/public/getting-started/provider-model-02-add-provider.png b/docs/docs/public/getting-started/provider-model-02-add-provider.png new file mode 100644 index 00000000..80e9eebb Binary files /dev/null and b/docs/docs/public/getting-started/provider-model-02-add-provider.png differ diff --git a/docs/docs/public/getting-started/provider-model-03-provider-dialog.png b/docs/docs/public/getting-started/provider-model-03-provider-dialog.png new file mode 100644 index 00000000..6a1a6217 Binary files /dev/null and b/docs/docs/public/getting-started/provider-model-03-provider-dialog.png differ diff --git a/docs/docs/public/getting-started/provider-model-04-provider-selected.png b/docs/docs/public/getting-started/provider-model-04-provider-selected.png new file mode 100644 index 00000000..f6685872 Binary files /dev/null and b/docs/docs/public/getting-started/provider-model-04-provider-selected.png differ diff --git a/docs/docs/style/terminology.md b/docs/docs/style/terminology.md deleted file mode 100644 index a510d624..00000000 --- a/docs/docs/style/terminology.md +++ /dev/null @@ -1,40 +0,0 @@ -# Terminology Rules - -> Audience: documentation contributors and maintainers. -> This page defines writing terms. It is not product user guidance. - -## Canonical Terms - -- **System Account (`User`)**: the account inside Memoh. -- **Platform Account (`ChannelIdentity`)**: the user's account on an external access platform, not a Memoh account. -- **Access Platform (`channel`)**: the external platform carrying inbound messages. -- **Account Linking (`bind`)**: linking a Platform Account to a System Account. -- **Bind Code**: one-time code used for account linking. -- **Bot**: resource and authorization boundary managed by a System Account. - -## Preferred Wording - -- Write **"platform account"** instead of "actor" in user-facing docs. -- Write **"access platform"** instead of "channel" when describing product behavior. -- Keep code aliases in parentheses on first mention: - - `Platform Account (ChannelIdentity)` - - `System Account (User)` - - `Account Linking (bind)` - -## Disallowed or Discouraged Terms - -- Avoid plain **actor** in conceptual docs (except when quoting code symbols). -- Avoid ambiguous **platform user** phrasing (it does not distinguish system vs platform account). -- Avoid wording that implies Platform Account is created inside Memoh. - -## Example Sentences - -- Correct: "A platform account is the user's TG account, not a Memoh account." -- Correct: "Account linking binds a platform account to a system account." -- Incorrect: "Actor is a user in Memoh." - -## Contributor Checklist - -- Is every "account" term clearly scoped (system vs platform)? -- Is "channel" replaced by "access platform" in prose? -- Are code aliases kept only as parenthetical references?