Memoh/AGENTS.md

AGENTS.md

Project Overview

Memoh is a multi-member, structured long-memory, containerized AI agent system platform. Users can create AI bots and chat with them via Telegram, Discord, Lark (Feishu), and more. Every bot has an independent container and memory system, allowing it to edit files, execute commands, and build itself — providing a secure, flexible, and scalable solution for multi-bot management.

Architecture Overview

The system consists of three core services:

Service	Tech Stack	Port	Description
Server (Backend)	Go + Echo	8080	Main service: REST API, auth, database, container management
Agent Gateway	Bun + Elysia	8081	AI chat gateway: handles chat requests and tool execution
Web (Frontend)	Vue 3 + Vite	8082	Management UI: visual configuration for Bots, Models, Channels, etc.

Infrastructure dependencies:

• PostgreSQL — Relational data storage
• Qdrant — Vector database for memory semantic search
• Containerd — Container runtime providing isolated environments per bot

Tech Stack

Backend (Go)

• Framework: Echo (HTTP)
• Dependency Injection: Uber FX
• Database Driver: pgx/v5
• Code Generation: sqlc (SQL → Go)
• API Docs: Swagger/OpenAPI (swaggo)
• Containers: containerd v2

Agent Gateway (TypeScript)

• Runtime: Bun
• Framework: Elysia

Frontend (TypeScript)

• Framework: Vue 3 (Composition API)
• Build Tool: Vite
• State Management: Pinia + Pinia Colada
• UI: Tailwind CSS + custom component library (@memoh/ui) + Reka UI
• Package Manager: pnpm monorepo

Tooling

• Task Runner: mise
• Package Managers: pnpm (frontend monorepo), Go modules (backend)

Project Structure

Memoh/
├── cmd/                        # Go application entry points
│   ├── agent/                  #   Main backend server (main.go)
│   ├── mcp/                    #   MCP server binary
│   └── cli/                    #   CLI tool
├── internal/                   # Go backend core code
│   ├── handlers/               #   HTTP handlers (REST API)
│   ├── services/               #   Business logic services
│   ├── db/                     #   Database layer
│   │   └── sqlc/               #   ⚠️ Auto-generated by sqlc — DO NOT modify manually
│   ├── channel/                #   Channel adapters (Telegram, Feishu, Local)
│   ├── memory/                 #   Memory / embedding system
│   ├── mcp/                    #   MCP protocol implementation
│   ├── conversation/           #   Conversation flow management
│   ├── bots/                   #   Bot management
│   └── containerd/             #   Container management
├── agent/                      # Agent Gateway (Bun/Elysia)
│   └── src/
├── packages/                   # Frontend monorepo
│   ├── web/                    #   Main web app (Vue 3)
│   ├── ui/                     #   Shared UI component library
│   ├── sdk/                    #   TypeScript SDK (auto-generated from OpenAPI)
│   ├── cli/                    #   TypeScript CLI
│   └── config/                 #   Shared configuration utilities
├── db/                         # Database
│   ├── migrations/             #   SQL migration files
│   └── queries/                #   SQL query files (sqlc input)
├── docker/                     # Docker configuration
├── docs/                       # Documentation site
├── scripts/                    # Utility scripts
├── config.toml.example         # Configuration template
├── docker-compose.yml          # Docker Compose orchestration
├── mise.toml                   # mise tasks and tool version definitions
└── sqlc.yaml                   # sqlc code generation config

Development Guide

Prerequisites

1. Install mise
2. Install toolchains and dependencies: mise install
3. Initialize the project: mise run setup
4. Copy the config file: cp config.toml.example config.toml and edit as needed
5. Start the dev environment: mise run dev

Common Commands

Command	Description
mise run dev	Start the full dev environment (backend + agent gateway + frontend)
mise run setup	Initialize dev environment (sqlc gen + DB migration + dependency install)
mise run sqlc-generate	Regenerate Go code after modifying SQL files
mise run swagger-generate	Generate Swagger documentation
mise run sdk-generate	Generate TypeScript SDK (depends on swagger-generate)
mise run db-up	Initialize and migrate the database
mise run db-down	Drop the database
mise run //agent:dev	Start Agent Gateway only
mise run //cmd/agent:start	Start the backend server only
mise run //packages/web:dev	Start the frontend dev server only

Docker Deployment

docker compose up -d        # Start all services
# Visit http://localhost:8082

Key Development Rules

Database, sqlc & Migrations

1. SQL queries are defined in db/queries/*.sql.
2. All Go files under internal/db/sqlc/ are auto-generated by sqlc. DO NOT modify them manually.
3. After modifying any SQL files (migrations or queries), run mise run sqlc-generate to update the generated Go code.

Migration Rules

Migrations live in db/migrations/ and follow a dual-update convention:

• 0001_init.up.sql is the canonical full schema. It always contains the complete, up-to-date database definition (all tables, indexes, constraints, etc.). When adding schema changes, you must also update 0001_init.up.sql to reflect the final state.
• Incremental migration files (0002_, 0003_, ...) contain only the diff needed to upgrade an existing database. They exist for environments that already have the schema and need to apply only the delta.
• Both must be kept in sync: every schema change requires updating 0001_init.up.sql AND creating a new incremental migration file.
• Naming: {NNNN}_{description}.up.sql and {NNNN}_{description}.down.sql, where {NNNN} is a zero-padded sequential number (e.g., 0005). Always use the next available number.
• Paired files: Every incremental migration must have both an .up.sql (apply) and a .down.sql (rollback) file.
• Header comment: Each file should start with a comment indicating the migration name and a brief description:

  -- 0005_add_feature_x
  -- Add feature_x column to bots table for ...
  

• Idempotent DDL: Use IF NOT EXISTS / IF EXISTS guards (e.g., CREATE TABLE IF NOT EXISTS, ADD COLUMN IF NOT EXISTS, DROP TABLE IF EXISTS) so migrations are safe to re-run.
• Down migration must fully reverse up: The .down.sql must cleanly undo everything its .up.sql does, in reverse order.
• After creating or modifying migrations, run mise run sqlc-generate to regenerate the Go code, then mise run db-up to apply.

API Development Workflow

1. Write handlers in internal/handlers/ with swaggo annotations.
2. Run mise run swagger-generate to update the OpenAPI docs.
3. Run mise run sdk-generate to update the frontend TypeScript SDK (packages/sdk/).
4. The frontend calls APIs via the auto-generated @memoh/sdk.

Frontend Development

• Use Vue 3 Composition API with <script setup> style.
• Shared components belong in packages/ui/.
• API calls use the auto-generated @memoh/sdk.
• State management uses Pinia; data fetching uses Pinia Colada.

Container Management

• macOS development requires running containerd via Lima (see .github/CONTRIBUTING.md).
• In Docker deployment, containerd runs as a standalone service.
• Each bot has its own isolated container instance.

Database Tables

Table	Description
users	User accounts (admin/member roles)
channel_identities	Unified identity system (cross-platform)
bots	Bot definitions with model references
bot_members	Bot membership (owner/admin/member)
bot_channel_configs	Per-bot channel configurations
bot_channel_routes	Conversation route mapping
bot_history_messages	Unified message history
llm_providers	LLM provider configurations
models	Model definitions (chat/embedding types)
mcp_connections	MCP connection configurations
containers	Bot container instances
snapshots	Container snapshots
schedule	Scheduled tasks (cron)
subagents	Sub-agent definitions
search_providers	Search engine provider configurations

Configuration

The main configuration file is config.toml (copied from config.toml.example), containing:

• [server] — HTTP listen address
• [admin] — Admin account credentials
• [auth] — JWT authentication settings
• [containerd] — Container runtime socket path
• [mcp] — MCP image and data configuration
• [postgres] — PostgreSQL connection
• [qdrant] — Qdrant vector database connection
• [agent_gateway] — Agent Gateway address
• [web] — Web frontend address
• [brave] — Brave Search API configuration