PNArchives/Memoh
1
0
Fork 0
mirror of https://github.com/memohai/Memoh.git synced 2026-04-27 07:16:19 +09:00
Code Issues Packages Projects Releases Wiki Activity
Files
cedac8dbf6e12d8398437263c7981a7247de2f0f
Memoh/AGENTS.md
T
BBQ d6aebf654f feat(devenv): add containerized development environment (#116) 
* feat(devenv): add containerized development environment

Replace local-process dev workflow with a fully containerized stack
using docker compose. This enables consistent development across
machines without requiring local Go/Node toolchains or containerd.

- Add Dockerfile.server.dev with containerd + CNI networking support
- Add Dockerfile.web.dev for frontend dev server
- Add server-dev-entrypoint.sh for containerd lifecycle management
- Expand devenv/docker-compose.yml with server, agent, web, migrate
  and deps services with proper health checks and dependency ordering
- Update app.dev.toml to use container service names instead of localhost
- Refactor mise.toml dev tasks to drive docker compose workflow
- Support agent_gateway.server_addr in config package for inter-container
  communication

* feat(devenv): add hot-reload and registry mirror support

- Add air for Go server hot-reload in dev containers
- Fix agent_gateway host in dev config (0.0.0.0 -> agent)
- Add configurable registry mirror for China mainland users
- Unify MCP image refs via MCPConfig.ImageRef()

* feat(scripts): add China mainland mirror option to install script

Prompt users to opt-in to memoh.cn mirror during installation,
which applies docker-compose.cn.yml overlay and sets registry
in config.toml for MCP image pulls.
2026-02-26 17:32:19 +08:00

197 lines
9.2 KiB
Markdown
Raw Blame History

# 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)
├── conf/ # Configuration templates (app.example.toml, app.dev.toml, app.docker.toml)
├── devenv/ # Development environment (docker-compose for local infra)
├── docker/ # Docker build & runtime (Dockerfiles, entrypoints, nginx.conf)
├── docs/ # Documentation site
├── scripts/ # Utility scripts
├── docker-compose.yml # Docker Compose orchestration (production)
├── mise.toml # mise tasks and tool version definitions
└── sqlc.yaml # sqlc code generation config
```
## Development Guide
### Prerequisites
1. Install [mise](https://mise.jdx.dev/)
2. Install toolchains and dependencies: `mise install`
3. Initialize the project: `mise run setup`
4. Start the dev environment: `mise run dev`
### Common Commands
| Command | Description |
|---------|-------------|
| `mise run dev` | Start the containerized dev environment (all services) |
| `mise run dev:down` | Stop the dev environment |
| `mise run dev:logs` | View dev environment logs |
| `mise run dev:restart` | Restart a service (e.g. `-- server`) |
| `mise run setup` | Copy config + install dependencies |
| `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 |
### Docker Deployment
```bash
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:
```sql
-- 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
- In Docker deployment, containerd runs inside the server container.
- 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 `conf/app.example.toml` or `conf/app.dev.toml` for development), 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
Reference in New Issue View Git Blame Copy Permalink