AGENTS.md

1# AGENTS.md
2 
3Repository instructions for AI coding agents. Keep this file short, concrete, and tied to commands that actually work in this
4repo. If a fact here conflicts with source files or CI config, trust the source file and update this guide.
5 
6## Project Snapshot
7 
8Memos is a self-hosted note-taking app.
9 
10- Backend: Go 1.26.2, Echo v5, Connect RPC, gRPC-Gateway, Protocol Buffers.
11- Frontend: React 19, TypeScript 6, Vite 8, Tailwind CSS v4, React Query v5.
12- Storage: SQLite, MySQL, PostgreSQL.
13- Generated API outputs: `proto/gen/` for Go/OpenAPI, `web/src/types/proto/` for TypeScript.
14 
15## Working Rules
16 
17- Read relevant code before editing; prefer local patterns over new abstractions.
18- Keep diffs scoped. Do not do repo-wide cleanup, dependency churn, or generated-file rewrites unless the task requires it.
19- Do not hand-edit generated proto outputs. Change `.proto` files, then run `buf generate`.
20- Add migrations for all database drivers when schema changes, and update each driver's `LATEST.sql`.
21- Add public API endpoints to `server/router/api/v1/acl_config.go`.
22- Ask before adding heavy dependencies, changing auth/token behavior, or altering Docker/release workflows.
23 
24## Commands
25 
26Run from the repository root unless a command starts with `cd`.
27 
28```bash
29# Backend
30go run ./cmd/memos --port 8081    # Start backend dev server
31go test ./...                      # Run all Go tests
32go test -v ./store/...             # Store tests, including DB drivers via TestContainers
33go test -v -race ./server/...      # Server tests with race detector
34go test -v -race ./internal/...    # Internal package tests with race detector
35go test -v -run TestFoo ./pkg/...  # Run matching Go tests
36go mod tidy -go=1.26.2             # Match CI tidy check
37golangci-lint run                  # Go lint, config: .golangci.yaml
38golangci-lint run --fix            # Auto-fix lint, including goimports
39 
40# Frontend
41cd web && pnpm install             # Install dependencies
42cd web && pnpm dev                 # Dev server on :3001, proxying API to :8081
43cd web && pnpm lint                # Type check + Biome lint
44cd web && pnpm test                # Vitest unit tests
45cd web && pnpm build               # Production build
46cd web && pnpm release             # Build SPA into server/router/frontend/dist
47 
48# Protocol Buffers
49cd proto && buf generate           # Regenerate Go + TypeScript + OpenAPI
50cd proto && buf lint               # Lint proto files
51cd proto && buf format -w          # Format proto files
52```
53 
54## Code Map
55 
56| Path | Purpose |
57| --- | --- |
58| `cmd/memos/main.go` | Cobra/Viper CLI setup and server startup |
59| `server/server.go` | Echo HTTP server and background runner wiring |
60| `server/auth/` | JWT access tokens, refresh tokens, PAT handling |
61| `server/router/api/v1/` | Connect/gRPC-Gateway services, ACL config, SSE hub |
62| `server/router/frontend/` | Static SPA serving |
63| `server/router/fileserver/` | Native HTTP file serving, thumbnails, range requests |
64| `server/runner/` | Background memo processing and S3 presign refresh |
65| `store/` | Store facade, cache, migrations, driver interface |
66| `store/db/{sqlite,mysql,postgres}/` | Database-specific drivers and SQL |
67| `proto/api/v1/` | Public API service definitions |
68| `proto/store/` | Internal storage proto messages |
69| `internal/` | App-private packages: scheduler, cron, email, CEL filter, markdown, idp, S3 |
70| `web/src/connect.ts` | Connect RPC clients, auth interceptor, access-token refresh |
71| `web/src/auth-state.ts` | Token storage and BroadcastChannel cross-tab sync |
72| `web/src/hooks/` | React Query hooks for server state |
73| `web/src/contexts/` | React context for client/UI state |
74| `web/src/components/` | Radix/Tailwind UI components and feature components |
75| `web/src/themes/` | CSS themes using OKLch color tokens |
76 
77## Change Routing
78 
79| Change | Update | Verify |
80| --- | --- | --- |
81| Go service or router behavior | Service code under `server/`, tests near package | `go test -v -race ./server/...` |
82| Store or migration behavior | `store/`, all three DB driver migrations, `LATEST.sql` | `go test -v ./store/...` |
83| Internal package logic | Relevant `internal/` package tests | `go test -v -race ./internal/...` |
84| Frontend behavior | Components/hooks/contexts under `web/src/` | `cd web && pnpm lint && pnpm test` |
85| Frontend production output | Vite config or release-sensitive UI | `cd web && pnpm build` or `pnpm release` |
86| Proto API | `.proto` source plus generated outputs | `cd proto && buf generate && buf lint` |
87| Public unauthenticated route | `server/router/api/v1/acl_config.go` | Targeted server test or manual route check |
88 
89## Go Conventions
90 
91- Wrap errors with `errors.Wrap(err, "context")` from `github.com/pkg/errors`; do not use `fmt.Errorf`.
92- Return service errors with `status.Errorf(codes.X, "message")`.
93- Keep imports grouped as stdlib, third-party, then `github.com/usememos/memos`; goimports is run by golangci-lint.
94- Add doc comments for exported identifiers; godot enforces exported comment punctuation.
95- Avoid package-level mutable state unless the surrounding package already uses that pattern.
96 
97## Frontend Conventions
98 
99- Use `@/` for absolute imports.
100- Follow Biome formatting: 2-space indent, double quotes, semicolons, 140-character line width.
101- Put server data in React Query hooks under `web/src/hooks/`; keep UI-only state in contexts or component state.
102- Use Tailwind CSS v4 utilities, `cn()` for class merging, and CVA for variants.
103- Reuse Radix primitives and existing components before adding new UI primitives.
104- Keep generated proto TypeScript under `web/src/types/proto/` out of manual edits and Biome rewrites.
105 
106## Database And Proto Rules
107 
108- Schema changes require SQLite, MySQL, and PostgreSQL migrations plus `LATEST.sql` updates.
109- Fresh-install SQL and incremental migrations must stay equivalent.
110- Proto field changes must preserve compatibility unless the task explicitly allows a breaking API change.
111- Regenerate after proto edits and include both Go/OpenAPI and TypeScript generated outputs.
112 
113## Verification Policy
114 
115- Run the narrowest relevant checks while iterating.
116- Before finishing, run the checks that match the changed surface from "Change Routing".
117- For docs-only changes, `git diff --check` is sufficient unless the docs include runnable examples that should be tested.
118- If a required check cannot run locally, report the reason and the exact command that remains.
119 
120## CI Reference
121 
122- Backend CI: Go 1.26.2, `go mod tidy -go=1.26.2`, golangci-lint v2.11.3, test groups `store`, `server`, `internal`, `other`.
123- Frontend CI: Node 24, pnpm 11.0.1, `pnpm lint`, `pnpm test`, `pnpm build`.
124- Proto CI: `buf lint` and `buf format` check.
125- Docker: `scripts/Dockerfile`, Alpine 3.21 runtime, non-root user, port 5230, multi-arch amd64/arm64/arm/v7.
126