diff --git a/docs/docs/.vitepress/config.ts b/docs/docs/.vitepress/config.ts index ef051e48..e735f6c8 100644 --- a/docs/docs/.vitepress/config.ts +++ b/docs/docs/.vitepress/config.ts @@ -34,6 +34,60 @@ export default defineConfig({ text: 'Getting Started', link: '/getting-started.md' }, + { + text: 'Installation', + items: [ + { + text: 'Docker', + link: '/installation/docker.md' + }, + { + text: 'config.toml', + link: '/installation/config-toml.md' + } + ] + }, + { + text: 'CLI', + items: [ + { + text: 'Overview', + link: '/cli/index.md' + }, + { + text: 'authentication', + link: '/cli/auth.md' + }, + { + text: 'config', + link: '/cli/config.md' + }, + { + text: 'provider', + link: '/cli/provider.md' + }, + { + text: 'model', + link: '/cli/model.md' + }, + { + text: 'bot', + link: '/cli/bot.md' + }, + { + text: 'channel', + link: '/cli/channel.md' + }, + { + text: 'schedule', + link: '/cli/schedule.md' + }, + { + text: 'chat', + link: '/cli/chat.md' + } + ] + }, { text: 'Core Concepts', items: [ diff --git a/docs/docs/cli/auth.md b/docs/docs/cli/auth.md new file mode 100644 index 00000000..231aab50 --- /dev/null +++ b/docs/docs/cli/auth.md @@ -0,0 +1,29 @@ +# Auth Commands + +## login + +Log in to the Memoh server. Prompts for username and password, then stores the JWT token in `~/.memoh/token.json`. + +```bash +memoh login +``` + +Interactive prompts: +- Username +- Password + +## logout + +Clear the stored token and log out. + +```bash +memoh logout +``` + +## whoami + +Show the current logged-in user (username, display name, user ID, role). Falls back to token info if the API call fails. + +```bash +memoh whoami +``` diff --git a/docs/docs/cli/bot.md b/docs/docs/cli/bot.md new file mode 100644 index 00000000..ac7f1864 --- /dev/null +++ b/docs/docs/cli/bot.md @@ -0,0 +1,83 @@ +# Bot Commands + +Manage bots and chat with them. + +## bot list + +List all bots. Admins can filter by owner. + +```bash +memoh bot list [options] +``` + +| Option | Description | +|--------|-------------| +| `--owner ` | Filter by owner user ID (admin only) | + +## bot create + +Create a new bot. Prompts for type and optionally name. + +```bash +memoh bot create [options] +``` + +| Option | Description | +|--------|-------------| +| `--type ` | `personal` or `public` | +| `--name ` | Display name | +| `--avatar ` | Avatar URL | +| `--active` | Set bot active | +| `--inactive` | Set bot inactive | + +## bot update + +Update bot info. Bot ID can be passed as argument or selected interactively. + +```bash +memoh bot update [id] [options] +``` + +| Option | Description | +|--------|-------------| +| `--name ` | Display name | +| `--avatar ` | Avatar URL | +| `--active` | Set bot active | +| `--inactive` | Set bot inactive | + +## bot delete + +Delete a bot. Asks for confirmation. + +```bash +memoh bot delete [id] +``` + +## bot chat + +Start an interactive streaming chat with a bot. + +```bash +memoh bot chat [id] +``` + +Type messages and press Enter. Type `exit` to quit. + +## bot set-model + +Enable a model for a bot (chat, memory, or embedding). + +```bash +memoh bot set-model [id] [options] +``` + +| Option | Description | +|--------|-------------| +| `--as ` | `chat`, `memory`, or `embedding` | +| `--model ` | Model ID | + +Example: + +```bash +memoh bot set-model my-bot-id --as chat --model gpt-4 +``` diff --git a/docs/docs/cli/channel.md b/docs/docs/cli/channel.md new file mode 100644 index 00000000..be887bc6 --- /dev/null +++ b/docs/docs/cli/channel.md @@ -0,0 +1,75 @@ +# Channel Commands + +Manage channels and bot/user channel configuration. + +## channel list + +List available channel types (e.g. telegram, feishu, local). + +```bash +memoh channel list +``` + +## channel info + +Show channel metadata and schema for a channel type. + +```bash +memoh channel info [type] +``` + +If `type` is omitted, prompts to select from available channels. + +## channel config get + +Get a bot's channel configuration. + +```bash +memoh channel config get [bot_id] [options] +``` + +| Option | Description | +|--------|-------------| +| `--type ` | Channel type | + +## channel config set + +Set a bot's channel configuration. Currently supports Feishu. + +```bash +memoh channel config set [bot_id] [options] +``` + +| Option | Description | +|--------|-------------| +| `--type ` | Channel type (e.g. `feishu`) | +| `--app_id ` | Feishu App ID | +| `--app_secret ` | Feishu App Secret | +| `--encrypt_key ` | Encrypt key (optional) | +| `--verification_token ` | Verification token (optional) | + +## channel bind get + +Get the current user's channel binding for a platform. + +```bash +memoh channel bind get [options] +``` + +| Option | Description | +|--------|-------------| +| `--type ` | Channel type | + +## channel bind set + +Set the current user's channel binding. Currently supports Feishu (open_id or user_id). + +```bash +memoh channel bind set [options] +``` + +| Option | Description | +|--------|-------------| +| `--type ` | Channel type (e.g. `feishu`) | +| `--open_id ` | Feishu Open ID | +| `--user_id ` | Feishu User ID | diff --git a/docs/docs/cli/chat.md b/docs/docs/cli/chat.md new file mode 100644 index 00000000..2fd2291d --- /dev/null +++ b/docs/docs/cli/chat.md @@ -0,0 +1,37 @@ +# Chat Commands + +## Default: Interactive Chat + +Running `memoh` with no subcommand starts an interactive chat. Use `--bot ` to specify which bot to chat with; otherwise you'll be prompted to select one. + +```bash +memoh [options] +memoh --bot +``` + +| Option | Description | +|--------|-------------| +| `--bot ` | Bot ID to chat with | + +Type your message and press Enter. Type `exit` to quit. Responses stream in real time. + +## tui + +Terminal UI chat session. Same behavior as the default chat but explicitly invoked. + +```bash +memoh tui [options] +memoh tui --bot +``` + +| Option | Description | +|--------|-------------| +| `--bot ` | Bot ID to chat with | + +## version + +Show the CLI version. + +```bash +memoh version +``` diff --git a/docs/docs/cli/config.md b/docs/docs/cli/config.md new file mode 100644 index 00000000..fc257d06 --- /dev/null +++ b/docs/docs/cli/config.md @@ -0,0 +1,38 @@ +# Config Commands + +The CLI stores its config in `~/.memoh/config.toml`. Use these commands to view or update it. + +## config + +Show the current config (host and port). + +```bash +memoh config +``` + +Output example: +``` +host = "127.0.0.1" +port = 8080 +``` + +## config set + +Update the config. Prompts for host and port if not provided via options. + +```bash +memoh config set [options] +``` + +| Option | Description | +|--------|-------------| +| `--host ` | API host (e.g. `127.0.0.1` or `api.example.com`) | +| `--port ` | API port (default: 8080) | + +Examples: + +```bash +memoh config set --host 192.168.1.100 --port 8080 +memoh config set +# Interactive prompts for host and port +``` diff --git a/docs/docs/cli/index.md b/docs/docs/cli/index.md new file mode 100644 index 00000000..691be1b8 --- /dev/null +++ b/docs/docs/cli/index.md @@ -0,0 +1,54 @@ +# Memoh CLI + +The Memoh CLI (`memoh`) is a command-line tool for managing bots, channels, providers, models, schedules, and chatting with bots. It talks to a running Memoh server via its API. + +## Installation + +The CLI is part of the Memoh monorepo. Install from source: + +```bash +git clone https://github.com/memohai/Memoh.git +cd Memoh +pnpm install +``` + +Run the CLI: + +```bash +cd packages/cli +pnpm start -- --help +``` + +To use `memoh` as a global command: + +```bash +cd packages/cli +pnpm build +pnpm link --global +memoh --help +``` + +Ensure your Memoh server is running (see [Docker installation](/installation/docker)) and the API is reachable at the configured host/port (default: `127.0.0.1:8080`). + +## Configuration + +The CLI stores config in `~/.memoh/config.toml` and auth token in `~/.memoh/token.json`. Use `memoh config` to view and `memoh config set` to change host/port. + +## Commands + +| Command | Description | +|---------|-------------| +| [login](./auth#login) | Log in to the Memoh server | +| [logout](./auth#logout) | Log out and clear token | +| [whoami](./auth#whoami) | Show current user | +| [config](./config) | Show or update CLI config (host, port) | +| [provider](./provider) | List, create, delete LLM providers | +| [model](./model) | List, create, delete models | +| [bot](./bot) | List, create, update, delete bots; chat; set model | +| [channel](./channel) | List channels; get/set bot channel config; get/set user binding | +| [schedule](./schedule) | List, create, update, toggle, delete bot schedules | +| [chat](./chat) | Interactive chat with a bot (default command) | +| [tui](./chat#tui) | Terminal UI chat session | +| [version](./chat#version) | Show CLI version | + +Most commands require authentication. Run `memoh login` first. diff --git a/docs/docs/cli/model.md b/docs/docs/cli/model.md new file mode 100644 index 00000000..a709e20c --- /dev/null +++ b/docs/docs/cli/model.md @@ -0,0 +1,51 @@ +# Model Commands + +Manage chat and embedding models. + +## model list + +List all models with their provider, type, and multimodal flag. + +```bash +memoh model list +``` + +## model create + +Create a new model. Prompts for provider, model ID, type, and (for embedding models) dimensions. + +```bash +memoh model create [options] +``` + +| Option | Description | +|--------|-------------| +| `--model_id ` | Model ID (e.g. `gpt-4`, `text-embedding-3-small`) | +| `--name ` | Display name | +| `--provider ` | Provider name | +| `--type ` | `chat` or `embedding` | +| `--dimensions ` | Embedding dimensions (required for embedding models) | +| `--multimodal` | Mark as multimodal | + +Examples: + +```bash +memoh model create --model_id gpt-4 --provider my-openai --type chat +memoh model create --model_id text-embedding-3-small --provider my-openai --type embedding --dimensions 1536 +memoh model create +# Interactive prompts +``` + +## model delete + +Delete a model by model ID. + +```bash +memoh model delete --model +``` + +Example: + +```bash +memoh model delete --model gpt-4 +``` diff --git a/docs/docs/cli/provider.md b/docs/docs/cli/provider.md new file mode 100644 index 00000000..ab953560 --- /dev/null +++ b/docs/docs/cli/provider.md @@ -0,0 +1,61 @@ +# Provider Commands + +Manage LLM providers (OpenAI, Anthropic, Ollama, etc.). + +## provider list + +List all providers. Optionally filter by provider name. + +```bash +memoh provider list [options] +``` + +| Option | Description | +|--------|-------------| +| `--provider ` | Filter by provider name | + +Examples: + +```bash +memoh provider list +memoh provider list --provider my-openai +``` + +## provider create + +Create a new provider. Prompts for any missing fields. + +```bash +memoh provider create [options] +``` + +| Option | Description | +|--------|-------------| +| `--name ` | Provider name | +| `--type ` | Client type | +| `--base_url ` | Base URL for the API | +| `--api_key ` | API key | + +Supported client types: `openai`, `openai-compat`, `anthropic`, `google`, `azure`, `bedrock`, `mistral`, `xai`, `ollama`, `dashscope` + +Examples: + +```bash +memoh provider create --name my-ollama --type ollama --base_url http://localhost:11434 +memoh provider create +# Interactive prompts +``` + +## provider delete + +Delete a provider by name. + +```bash +memoh provider delete --provider +``` + +Example: + +```bash +memoh provider delete --provider my-ollama +``` diff --git a/docs/docs/cli/schedule.md b/docs/docs/cli/schedule.md new file mode 100644 index 00000000..62310eac --- /dev/null +++ b/docs/docs/cli/schedule.md @@ -0,0 +1,71 @@ +# Schedule Commands + +Manage cron-based schedules for bots. All schedule commands require `--bot ` to specify the bot. + +## schedule list + +List all schedules for a bot. + +```bash +memoh schedule list --bot +``` + +## schedule get + +Get a schedule by ID. + +```bash +memoh schedule get --bot +``` + +## schedule create + +Create a new schedule. Prompts for name, description, cron pattern, command, and optional max calls. + +```bash +memoh schedule create [options] --bot +``` + +| Option | Description | +|--------|-------------| +| `--name ` | Schedule name | +| `--description ` | Description | +| `--pattern ` | Cron pattern (e.g. `0 9 * * *` for daily at 9am) | +| `--command ` | Command to run in the bot container | +| `--max_calls ` | Max executions (optional, empty for unlimited) | +| `--enabled` | Create as enabled | +| `--disabled` | Create as disabled | + +## schedule update + +Update a schedule. + +```bash +memoh schedule update [options] --bot +``` + +| Option | Description | +|--------|-------------| +| `--name ` | Schedule name | +| `--description ` | Description | +| `--pattern ` | Cron pattern | +| `--command ` | Command | +| `--max_calls ` | Max executions | +| `--enabled` | Enable | +| `--disabled` | Disable | + +## schedule toggle + +Enable or disable a schedule (flip current state). + +```bash +memoh schedule toggle --bot +``` + +## schedule delete + +Delete a schedule. + +```bash +memoh schedule delete --bot +``` diff --git a/docs/docs/getting-started.md b/docs/docs/getting-started.md index 8b3a7945..b1e9d291 100644 --- a/docs/docs/getting-started.md +++ b/docs/docs/getting-started.md @@ -1 +1,75 @@ -# Getting Started \ No newline at end of file +# Getting Started + +## 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, Lark (Feishu), and more. 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. + +## Key Features + +### Multi-Bot Management + +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. + +### Containerized Isolation + +Each bot runs in its own isolated container (powered by Containerd) with a separate filesystem and network. Bots can freely read/write files and execute commands within their containers without interfering with each other. + +### Memory Engineering + +A deeply engineered memory layer inspired by Mem0: + +- Automatically extracts key facts from each conversation turn and stores them as structured memories +- Supports semantic search (via Qdrant vector database) and keyword retrieval (BM25) +- Loads the last 24 hours of conversation context by default +- Automatic memory compaction to keep the memory store lean +- Multi-language auto-detection + +### Multi-Platform Support + +Unified channel adapter architecture for connecting to multiple messaging platforms: + +- **Telegram** — Full support with streaming, Markdown, attachments, and replies +- **Lark (Feishu)** — Full support +- **Web** — Built-in web chat interface +- **CLI** — Command-line chat + +### Agent Capabilities + +Bots come with a rich set of built-in tools: + +- **Web Search** — Brave Search integration for real-time information +- **Subagents** — Create specialized subagents, assign skills, and delegate complex tasks +- **Skills** — Configurable skill system to extend bot capabilities +- **Container Operations** — Read/write files, edit code, and execute commands inside the container +- **Memory Management** — Search and manage memories +- **Messaging** — Send messages and reactions + +### Multi-LLM Provider Support + +Flexibly switch between a wide range of LLM providers: + +- OpenAI, Anthropic, Google, Azure, AWS Bedrock +- Mistral, XAI, Ollama, Dashscope (Qwen), and more + +### MCP Protocol Support + +Supports Model Context Protocol (MCP) via HTTP and SSE to connect external tool services. Each bot can have its own independent MCP connections. + +### Scheduled Tasks + +Configure scheduled tasks using cron expressions to automatically run commands at specified times. Supports max execution count limits and manual triggers. + +### Graphical Configuration + +Configure bots, channels, providers, models, MCP, skills, and all other settings through a web management UI — no coding required to set up your own AI bot. + +### CLI Tool + +A command-line tool for bot management, channel configuration, model management, streaming chat, and more — designed for developers who prefer the terminal. See [CLI documentation](/cli/). + +## Installation + +To get Memoh running: + +- **[Docker](/installation/docker)** — Recommended. One-click or manual setup with Docker Compose. Includes all services (PostgreSQL, Qdrant, Containerd, server, agent, web) — no extra dependencies on the host. +- **[config.toml](/installation/config-toml)** — Reference for all configuration fields. diff --git a/docs/docs/index.md b/docs/docs/index.md index 076fe5a9..8ee8bb5b 100644 --- a/docs/docs/index.md +++ b/docs/docs/index.md @@ -1,22 +1,14 @@ # Memoh Documentation -Memoh is a multi-member, long-memory, containerized AI agent system. +Memoh is a multi-member, structured long-memory, containerized AI agent system. Create your own AI bots, chat with them via Telegram, Lark (Feishu), Web, or CLI. Each bot runs in an isolated container with its own memory system — able to edit files, run commands, and access the network. -## Documentation Sections +## Documentation -- [Getting Started](/getting-started.md) -- [Core Concepts](/concepts/index.md) +- **[Getting Started](/getting-started)** — What Memoh is, key features, and installation links. +- **[Installation](/installation/docker)** — [Docker](/installation/docker) (recommended) and [config.toml](/installation/config-toml) reference. +- **[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.md) - -## Current Focus - -The current documentation iteration focuses on account semantics: - -- Distinguishing system accounts and platform accounts -- Explaining why account linking is account-scoped -- Clarifying the relationship between account linking and bot access - -Note: "platform account" means the user's account on external platforms (for example, TG), not a Memoh account. +- [Terminology Rules](/style/terminology) — Documentation style guide. diff --git a/docs/docs/installation/config-toml.md b/docs/docs/installation/config-toml.md new file mode 100644 index 00000000..8b58ac9a --- /dev/null +++ b/docs/docs/installation/config-toml.md @@ -0,0 +1,152 @@ +# config.toml Reference + +Memoh uses a TOML configuration file. By default it looks for `config.toml` in the current directory. With Docker, you can mount a custom config via `MEMOH_CONFIG` (see [Docker installation](./docker#custom-configuration)). + +## Full Example + +```toml +[log] +level = "info" +format = "text" + +[server] +addr = ":8080" + +[admin] +username = "admin" +password = "change-your-password" +email = "admin@example.com" + +[auth] +jwt_secret = "your-secret-from-openssl-rand-base64-32" +jwt_expires_in = "168h" + +[containerd] +socket_path = "/run/containerd/containerd.sock" +namespace = "default" + +[mcp] +image = "docker.io/library/memoh-mcp:latest" +snapshotter = "overlayfs" +data_root = "data" +data_mount = "/data" + +[postgres] +host = "127.0.0.1" +port = 5432 +user = "postgres" +password = "your-password" +database = "memoh" +sslmode = "disable" + +[qdrant] +base_url = "http://127.0.0.1:6334" +api_key = "" +collection = "memory" +timeout_seconds = 10 + +[agent_gateway] +host = "127.0.0.1" +port = 8081 + +[web] +host = "127.0.0.1" +port = 8082 + +[brave] +api_key = "" +base_url = "https://api.search.brave.com/res/v1/" +``` + +## Section Reference + +### `[log]` + +| Field | Type | Default | Description | +|---------|--------|---------|--------------------------------------------------| +| `level` | string | `"info"` | Log level: `debug`, `info`, `warn`, `error` | +| `format`| string | `"text"` | Log format: `text` or `json` | + +### `[server]` + +| Field | Type | Default | Description | +|--------|--------|---------|--------------------------------------------------| +| `addr` | string | `":8080"` | HTTP listen address. Use `:8080` for all interfaces, or `host:port` (e.g. `server:8080` in Docker). | + +### `[admin]` + +| Field | Type | Default | Description | +|------------|--------|---------|--------------------------------------| +| `username` | string | `"admin"` | Admin login username | +| `password` | string | — | Admin login password. **Change in production.** | +| `email` | string | — | Admin email (for display) | + +### `[auth]` + +| Field | Type | Default | Description | +|----------------|--------|---------|--------------------------------------------------| +| `jwt_secret` | string | — | Secret for signing JWT tokens. **Required.** Generate with `openssl rand -base64 32`. | +| `jwt_expires_in` | string | `"24h"` | JWT expiration, e.g. `"24h"`, `"168h"` (7 days) | + +### `[containerd]` + +| Field | Type | Default | Description | +|---------------|--------|---------|--------------------------------------------------| +| `socket_path` | string | `"/run/containerd/containerd.sock"` | Path to containerd socket | +| `namespace` | string | `"default"` | Containerd namespace for bot containers | + +### `[mcp]` + +MCP (Model Context Protocol) container configuration. Each bot runs in a container built from this image. + +| Field | Type | Default | Description | +|---------------|--------|---------|--------------------------------------------------| +| `image` | string | `"docker.io/library/memoh-mcp:latest"` | MCP container image | +| `snapshotter` | string | `"overlayfs"` | Containerd snapshotter | +| `data_root` | string | `"data"` | Host path for bot data (Docker: `/opt/memoh/data`) | +| `data_mount` | string | `"/data"` | Path inside container where data is mounted | + +### `[postgres]` + +| Field | Type | Default | Description | +|-----------|--------|---------|--------------------------------------------------| +| `host` | string | `"127.0.0.1"` | PostgreSQL host | +| `port` | int | `5432` | PostgreSQL port | +| `user` | string | `"postgres"` | Database user | +| `password`| string | — | Database password | +| `database`| string | `"memoh"` | Database name | +| `sslmode` | string | `"disable"` | SSL mode: `disable`, `require`, `verify-ca`, `verify-full` | + +### `[qdrant]` + +| Field | Type | Default | Description | +|------------------|--------|---------|--------------------------------------------------| +| `base_url` | string | `"http://127.0.0.1:6334"` | Qdrant HTTP API URL | +| `api_key` | string | `""` | Optional API key for Qdrant Cloud | +| `collection` | string | `"memory"` | Vector collection name for memories | +| `timeout_seconds`| int | `10` | Request timeout in seconds | + +### `[agent_gateway]` + +| Field | Type | Default | Description | +|--------|--------|---------|--------------------------------------------------| +| `host` | string | `"127.0.0.1"` | Agent gateway bind host | +| `port` | int | `8081` | Agent gateway port | + +In Docker Compose, `host` is typically `"agent"` (service name). The agent reads `[server].addr` to call the main API. + +### `[web]` + +| Field | Type | Default | Description | +|--------|--------|---------|--------------------------------------------------| +| `host` | string | `"127.0.0.1"` | Web UI bind host | +| `port` | int | `8082` | Web UI port | + +### `[brave]` + +Brave Search API for the web search tool. Leave `api_key` empty to disable web search. + +| Field | Type | Default | Description | +|-----------|--------|---------|--------------------------------------------------| +| `api_key` | string | `""` | Brave Search API key. Get one at [brave.com/search/api](https://brave.com/search/api). | +| `base_url`| string | `"https://api.search.brave.com/res/v1/"` | Brave Search API base URL | diff --git a/docs/docs/installation/docker.md b/docs/docs/installation/docker.md new file mode 100644 index 00000000..db6e9fb9 --- /dev/null +++ b/docs/docs/installation/docker.md @@ -0,0 +1,121 @@ +# Docker Installation + +Docker is the recommended way to run Memoh. The stack includes PostgreSQL, Qdrant, Containerd, the main server, agent gateway, and web UI — all orchestrated via Docker Compose. You do not need to install containerd, nerdctl, or buildkit on your host; everything runs inside containers. + +## Prerequisites + +- [Docker](https://docs.docker.com/get-docker/) +- [Docker Compose v2](https://docs.docker.com/compose/install/) +- Git + +## One-Click Install + +Run the official install script (requires Docker and Docker Compose): + +```bash +curl -fsSL https://raw.githubusercontent.com/memohai/Memoh/main/scripts/install.sh | sh +``` + +The script will: + +1. Check for Docker and Docker Compose +2. Prompt for configuration (workspace, data directory, admin credentials, JWT secret, Postgres password) +3. Clone the repository +4. Generate `config.toml` from the Docker template +5. Start all services with `docker compose up -d --build` + +**Silent install** (use all defaults, no prompts): + +```bash +curl -fsSL https://raw.githubusercontent.com/memohai/Memoh/main/scripts/install.sh | sh -s -- -y +``` + +Defaults when running silently: + +- Workspace: `~/memoh` +- Data directory: `~/memoh/data` +- Admin: `admin` / `admin123` +- JWT secret: auto-generated +- Postgres password: `memoh123` + +## Manual Install + +Clone the repository and start with Docker Compose: + +```bash +git clone https://github.com/memohai/Memoh.git +cd Memoh +docker compose up -d +``` + +By default, Docker Compose uses `docker/config/config.docker.toml`. No config file in the project root is mounted — only this built-in config is used. See [config.toml reference](./config-toml) for all configuration fields. + +## Access Points + +After startup: + +| Service | URL | +|---------------|------------------------| +| Web UI | http://localhost:8082 | +| API | http://localhost:8080 | +| Agent Gateway | http://localhost:8081 | + +Default login: `admin` / `admin123` + +First startup may take 1–2 minutes while images build and services initialize. + +## Custom Configuration + +To use your own config file: + +1. Copy the Docker config template and edit it. See [config.toml reference](./config-toml) for field descriptions: + +```bash +cp docker/config/config.docker.toml config.toml +nano config.toml +``` + +2. Point `MEMOH_CONFIG` at your config when starting (path is on the host; run `docker compose` from the project root): + +```bash +MEMOH_CONFIG=./config.toml docker compose up -d +``` + +**Recommended changes for production** (see [config.toml reference](./config-toml) for details): + +- `admin.password` — Change the admin password +- `auth.jwt_secret` — Generate with `openssl rand -base64 32` +- `postgres.password` — Change the database password (and set `POSTGRES_PASSWORD` when running `docker compose`) + +## Common Commands + +```bash +docker compose up -d # Start +docker compose down # Stop +docker compose logs -f # View logs +docker compose ps # Status +docker compose up -d --build # Rebuild and restart +``` + +## Production Checklist + +1. **HTTPS** — Configure SSL (e.g. via `docker-compose.override.yml` with certs) +2. **Passwords** — Change all default passwords and secrets +3. **Firewall** — Restrict access to necessary ports +4. **Resource limits** — Set memory/CPU limits for containers +5. **Backups** — Regular backups of Postgres and Qdrant data + +## Troubleshooting + +```bash +docker compose logs server # View main service logs +docker compose logs containerd # View containerd logs +docker compose config # Validate configuration +docker compose build --no-cache && docker compose up -d # Full rebuild +``` + +## Security Warnings + +- The main service runs with privileged container access — only run in trusted environments +- You must change all default passwords and secrets before production use +- Use HTTPS in production