memos/CLAUDE.md

CLAUDE.md

Memos — self-hosted knowledge management platform. Go 1.25 backend, React 18 + TypeScript + Vite 7 frontend, Protocol Buffers API.

See AGENTS.md for full architecture, workflows, and patterns.

Essential Commands

Backend

go run ./cmd/memos --port 8081    # Start dev server
go test ./...                      # Run all tests
golangci-lint run                  # Lint
goimports -w .                     # Format imports

Frontend

cd web && pnpm install             # Install deps
pnpm dev                           # Dev server (proxies to :8081)
pnpm lint                          # Type check + Biome lint
pnpm lint:fix                      # Auto-fix lint issues
pnpm format                        # Format code
pnpm build                         # Production build

Protocol Buffers

cd proto && buf generate            # Regenerate Go + TypeScript
cd proto && buf lint                # Lint proto files

Key Rules

• Go errors: Use errors.Wrap(err, "context") from github.com/pkg/errors. Never use fmt.Errorf.
• Go imports: stdlib → third-party → local (github.com/usememos/memos). Run goimports -w ..
• Go comments: All exported functions must have doc comments (godot enforced).
• Go gRPC errors: Return status.Errorf(codes.X, "message") from service methods.
• Frontend imports: Use @/ alias for absolute imports.
• Frontend formatting: Biome — 140 char lines, double quotes, always semicolons, 2-space indent.
• Frontend state: Server data via React Query hooks (web/src/hooks/). Client state via React Context.
• Database changes: Must provide migration files for all 3 drivers (sqlite, mysql, postgres) and update LATEST.sql.
• Proto changes: Run buf generate after editing .proto files. Generated code is in proto/gen/ and web/src/types/proto/.
• Public endpoints: Add to server/router/api/v1/acl_config.go.