Skip to content

AGENTS.md

Latest commit

 

History

History
125 lines (100 loc) · 6.67 KB

AGENTS.md

File metadata and controls

125 lines (100 loc) · 6.67 KB

AGENTS.md

Repository instructions for AI coding agents. Keep this file short, concrete, and tied to commands that actually work in this repo. If a fact here conflicts with source files or CI config, trust the source file and update this guide.

Project Snapshot

Memos is a self-hosted note-taking app.

  • Backend: Go 1.26.2, Echo v5, Connect RPC, gRPC-Gateway, Protocol Buffers.
  • Frontend: React 19, TypeScript 6, Vite 8, Tailwind CSS v4, React Query v5.
  • Storage: SQLite, MySQL, PostgreSQL.
  • Generated API outputs: proto/gen/ for Go/OpenAPI, web/src/types/proto/ for TypeScript.

Working Rules

  • Read relevant code before editing; prefer local patterns over new abstractions.
  • Keep diffs scoped. Do not do repo-wide cleanup, dependency churn, or generated-file rewrites unless the task requires it.
  • Do not hand-edit generated proto outputs. Change .proto files, then run buf generate.
  • Add migrations for all database drivers when schema changes, and update each driver's LATEST.sql.
  • Add public API endpoints to server/router/api/v1/acl_config.go.
  • Ask before adding heavy dependencies, changing auth/token behavior, or altering Docker/release workflows.

Commands

Run from the repository root unless a command starts with cd.

# Backend
go run ./cmd/memos --port 8081    # Start backend dev server
go test ./...                      # Run all Go tests
go test -v ./store/...             # Store tests, including DB drivers via TestContainers
go test -v -race ./server/...      # Server tests with race detector
go test -v -race ./internal/...    # Internal package tests with race detector
go test -v -run TestFoo ./pkg/...  # Run matching Go tests
go mod tidy -go=1.26.2             # Match CI tidy check
golangci-lint run                  # Go lint, config: .golangci.yaml
golangci-lint run --fix            # Auto-fix lint, including goimports

# Frontend
cd web && pnpm install             # Install dependencies
cd web && pnpm dev                 # Dev server on :3001, proxying API to :8081
cd web && pnpm lint                # Type check + Biome lint
cd web && pnpm test                # Vitest unit tests
cd web && pnpm build               # Production build
cd web && pnpm release             # Build SPA into server/router/frontend/dist

# Protocol Buffers
cd proto && buf generate           # Regenerate Go + TypeScript + OpenAPI
cd proto && buf lint               # Lint proto files
cd proto && buf format -w          # Format proto files

Code Map

Path Purpose
cmd/memos/main.go Cobra/Viper CLI setup and server startup
server/server.go Echo HTTP server and background runner wiring
server/auth/ JWT access tokens, refresh tokens, PAT handling
server/router/api/v1/ Connect/gRPC-Gateway services, ACL config, SSE hub
server/router/frontend/ Static SPA serving
server/router/fileserver/ Native HTTP file serving, thumbnails, range requests
server/runner/ Background memo processing and S3 presign refresh
store/ Store facade, cache, migrations, driver interface
store/db/{sqlite,mysql,postgres}/ Database-specific drivers and SQL
proto/api/v1/ Public API service definitions
proto/store/ Internal storage proto messages
internal/ App-private packages: scheduler, cron, email, CEL filter, markdown, idp, S3
web/src/connect.ts Connect RPC clients, auth interceptor, access-token refresh
web/src/auth-state.ts Token storage and BroadcastChannel cross-tab sync
web/src/hooks/ React Query hooks for server state
web/src/contexts/ React context for client/UI state
web/src/components/ Radix/Tailwind UI components and feature components
web/src/themes/ CSS themes using OKLch color tokens

Change Routing

Change Update Verify
Go service or router behavior Service code under server/, tests near package go test -v -race ./server/...
Store or migration behavior store/, all three DB driver migrations, LATEST.sql go test -v ./store/...
Internal package logic Relevant internal/ package tests go test -v -race ./internal/...
Frontend behavior Components/hooks/contexts under web/src/ cd web && pnpm lint && pnpm test
Frontend production output Vite config or release-sensitive UI cd web && pnpm build or pnpm release
Proto API .proto source plus generated outputs cd proto && buf generate && buf lint
Public unauthenticated route server/router/api/v1/acl_config.go Targeted server test or manual route check

Go Conventions

  • Wrap errors with errors.Wrap(err, "context") from github.com/pkg/errors; do not use fmt.Errorf.
  • Return service errors with status.Errorf(codes.X, "message").
  • Keep imports grouped as stdlib, third-party, then github.com/usememos/memos; goimports is run by golangci-lint.
  • Add doc comments for exported identifiers; godot enforces exported comment punctuation.
  • Avoid package-level mutable state unless the surrounding package already uses that pattern.

Frontend Conventions

  • Use @/ for absolute imports.
  • Follow Biome formatting: 2-space indent, double quotes, semicolons, 140-character line width.
  • Put server data in React Query hooks under web/src/hooks/; keep UI-only state in contexts or component state.
  • Use Tailwind CSS v4 utilities, cn() for class merging, and CVA for variants.
  • Reuse Radix primitives and existing components before adding new UI primitives.
  • Keep generated proto TypeScript under web/src/types/proto/ out of manual edits and Biome rewrites.

Database And Proto Rules

  • Schema changes require SQLite, MySQL, and PostgreSQL migrations plus LATEST.sql updates.
  • Fresh-install SQL and incremental migrations must stay equivalent.
  • Proto field changes must preserve compatibility unless the task explicitly allows a breaking API change.
  • Regenerate after proto edits and include both Go/OpenAPI and TypeScript generated outputs.

Verification Policy

  • Run the narrowest relevant checks while iterating.
  • Before finishing, run the checks that match the changed surface from "Change Routing".
  • For docs-only changes, git diff --check is sufficient unless the docs include runnable examples that should be tested.
  • If a required check cannot run locally, report the reason and the exact command that remains.

CI Reference

  • Backend CI: Go 1.26.2, go mod tidy -go=1.26.2, golangci-lint v2.11.3, test groups store, server, internal, other.
  • Frontend CI: Node 24, pnpm 11.0.1, pnpm lint, pnpm test, pnpm build.
  • Proto CI: buf lint and buf format check.
  • Docker: scripts/Dockerfile, Alpine 3.21 runtime, non-root user, port 5230, multi-arch amd64/arm64/arm/v7.