13 KiB
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.27.2, net/http, Connect RPC, gRPC-Gateway, Protocol Buffers.
- Frontend: React 19, TypeScript 7, Vite 8, Tailwind CSS v4,
@usememos/uion Base UI, 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
.protofiles, then runbuf generate. - Add migrations for all database drivers when schema changes, and update each driver's
LATEST.sql. - Add public API endpoints to
server/api/acl_config.go. - Ask before adding heavy dependencies, changing auth/token behavior, or altering Docker/release workflows.
Documentation
- ADRs and their companion glossary have been retired. Do not recreate them unless explicitly requested.
- Design documents in
docs/design/stay editable until the feature ships in a tagged release; keep a merged-but-unreleased design in step with its implementation. After release the body is frozen: record later design changes in a dated## Amendmentssection at the end, never by rewriting the body. Seedocs/design/README.md. Verify current behavior in source code and tests, not in design documents. - Brand copy (tagline, descriptions, README intro) comes verbatim from
BRAND.mdinusememos/.github. Change it there first; do not keep brand guidelines in this repo. - Keep contributor guidance in this file and package-local
README.mdordoc.gofiles current when relevant code changes.
Commands
Run from the repository root unless a command starts with cd.
# Backend
go run -buildvcs=true ./cmd/memos --port 8081 # Start backend with commit-derived CalVer
go run -buildvcs=true ./cmd/memos config plan --data DIR --config-dir DIR # Declarative configuration: also validate, apply, state
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 ./core/... # Run matching Go tests in one tree
go mod tidy -go=1.27.2 # Match CI tidy check
go fix ./... # Apply Go modernization fixes
go fix -diff ./... # Match CI modernization check
golangci-lint run # Go lint, config: .golangci.yaml (includes depguard layering rules)
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 (or $DEV_PROXY_SERVER)
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/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
Repository Layout
Every root folder is named for what it holds. Read the folder's doc.go or README.md before adding to it.
| Path | Holds | May import |
|---|---|---|
cmd/memos/ |
Cobra/Viper CLI setup and server startup | anything |
server/ |
The HTTP process: net/http bootstrap, graceful shutdown, every transport | core, store, provider, markdown, filter, internal |
server/api/ |
Connect/gRPC-Gateway services, ACL config, SSE hub. Thin handlers; rules go to core/ |
|
server/fileserver/ |
Native HTTP file serving, thumbnails, range requests | |
server/frontend/ |
Static SPA serving; dist/ is the built SPA baked in by go:embed |
|
server/mcp/ |
Model Context Protocol server | |
server/auth/ |
JWT access tokens, refresh tokens, PAT handling | |
core/ |
Business rules with no HTTP and no SQL: access, notification, memopayload, memoexport, usagelimit, identityprovider, instancesetting, user, configuration |
store, provider, markdown, filter, internal |
store/ |
Store facade, cache, migrations, Driver interface; store/db/{sqlite,mysql,postgres}/ implement it |
provider, markdown, filter, internal |
markdown/ |
Markdown engine: parser, AST, memos syntax extensions, renderer, memo payload | proto/gen, internal |
filter/ |
CEL filter compiler: parse to IR, render to SQL per driver, filterable field schema | internal |
provider/ |
Backends configured by instance settings: ai, idp, storage |
proto/gen, internal |
internal/ |
Private plumbing with no memos vocabulary (identifier, email, webhook, ratelimit, …) |
third party only |
proto/api/, proto/store/ |
Public API and internal storage proto sources; proto/gen/ is generated |
|
web/src/ |
React SPA: connect.ts clients, auth-state.ts, hooks/, contexts/, components/, lib/, locales/, themes/ |
Layering rules, enforced by depguard in .golangci.yaml:
- Imports point downward only:
cmd→server→core→store→ {provider,markdown,filter} →internal. internal/packages import nothing from this module (exceptinternal/testutil, which may importproto/gen).- A package goes in
internal/only if it could be published as a standalone module unchanged. If it knows what a Memo, Space, or instance setting is, it is a root package. - Never create
util,common,base,helpers,misc, orpkgpackages. Name a package for the one thing it does, or put the code next to its only caller. - New business rules extracted from
server/apigo tocore/<resource>/, one package per resource.
File convention inside server/api/: <resource>_service.go holds the RPC handlers, <resource>_service_converters.go the
store↔proto conversion, and <resource>_service_<topic>.go further splits. Extend the matching file; do not add *_helpers2.go.
Identity providers and instance settings are the exception: declarative configuration files use their API messages, so their
conversion lives in core/identityprovider and core/instancesetting, and server/api keeps only response redaction.
Black-box service tests live in server/api/test/, unit tests next to the code.
Change Routing
| Change | Update | Verify |
|---|---|---|
| Go service or router behavior | Handlers under server/, rules under core/, tests near package |
go test -v -race ./server/... ./core/... |
| Store or migration behavior | store/, all three DB driver migrations, LATEST.sql |
go test -v ./store/... |
| Markdown, filter, or provider logic | markdown/, filter/, provider/ |
go test -v -race ./markdown/... ./filter/... ./provider/... |
| 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, generated outputs, proto/api/CHANGELOG.md for breaks |
cd proto && buf generate && buf lint |
| Public unauthenticated route | server/api/acl_config.go |
Targeted server test or manual route check |
Go Conventions
- Wrap errors with
errors.Wrap(err, "context")fromgithub.com/pkg/errors; do not usefmt.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. - Show, edit and compose memos through
web/src/components/MemoEditor(a name or draft seed plus a mode); see itsREADME.md. - Keep generated proto TypeScript under
web/src/types/proto/out of manual edits and Biome rewrites. - UI work reads
web/node_modules/@usememos/ui/llms.txtfirst:@usememos/uiis the design system (tokens, type classes, components). Controls come from the package; build a part it lacks on Base UI as itscustom-components.mddescribes. - Use a package component when one fits (
Button,Link,Spinner,Badge). Its class functions (buttonClasses(),menuClasses(),badgeClasses()) are for elements it can't render, such as a router link or a Base UI trigger. - Style with Tailwind CSS v4 and the package's
mu-utilities (bg-mu-surface,text-mu-text-secondary,rounded-mu-md), text with its type classes (mu-caption,mu-body,mu-label,mu-title), andcn()for class merging. No Tailwind text sizes or old color names (muted-foreground,destructive,popover). The exceptions are the brand wordmark and emoji glyphs, whose font size is their icon box (SpaceIcon,SpaceMark,MemoViewIcon,CustomIconPicker). - Custom controls using
mu-focusmust reserve a real 1px border (transparent for borderless controls). - Focus shows through
mu-focus. Never addring-*orfocus-visible:ring-*, and never pairmu-focuswithoutline-none, which overrides it. Visually hidden text usesmu-visually-hidden; a control that appears on focus keeps Tailwind'ssr-only focus-visible:not-sr-onlypair. - Report failures with
showErrorToastfromweb/src/lib/toast.ts. A form's own validation errors go under the field (Field.Error, kept inuseFieldErrors), not in a toast. - Every new key in
web/src/locales/en.jsonis translated into all locales;tests/locale-resources.test.tsfails otherwise. A plural message is stored askey_one,key_other, … and looked up by its base key withcount. - Lucide icons outside a package control take a size class that sets box and stroke together:
mu-icon-xs(12px),mu-icon-sm(14px) ormu-icon(16px). No Tailwind sizes on 12–16px icons and nostrokeWidth.
Database And Proto Rules
- Schema changes require SQLite, MySQL, and PostgreSQL migrations plus
LATEST.sqlupdates. - Fresh-install SQL and incremental migrations must stay equivalent.
- Proto field changes must preserve compatibility unless the task explicitly allows a breaking API change. Record every
allowed break in
proto/api/CHANGELOG.md; compatibility is checked during review. - 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 --checkis 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
-
Releases are cut by pushing a
YY.MM.N[-rc.K]tag. To cut, promote, or check a release, follow.agents/skills/release/SKILL.md. -
Development builds use the HEAD committer date in UTC as
YY.MM.D-dev.<sha7>; release builds inject the CalVer tag. -
go buildembeds Git metadata automatically;go runneeds-buildvcs=true. Builds without Git metadata must injectgithub.com/usememos/memos/internal/version.Versionthrough-ldflags. -
Docker excludes
.git; pass--build-arg VERSION="$(bash scripts/release_version.sh development-version)"and--build-arg COMMIT="$(git rev-parse HEAD)"when building locally (build frontend assets first). -
Workflows install toolchains through
.github/actions/setup-go(Go version fromgo.mod) and.github/actions/setup-web(pnpm fromweb/package.json, Node 24,pnpm install); change versions there, not per workflow. -
Backend CI: Go 1.27.2,
go mod tidy,go fix -diff ./..., golangci-lint v2.14.0 (including goimports), test groupsstore,server,internal,other(cmd,core,markdown,filter,provider,proto). -
Frontend CI: Node 24, pnpm 11.0.1,
pnpm lint,pnpm test,pnpm build. -
Proto CI:
buf lintandbuf formatcheck. -
Docker:
scripts/Dockerfile, Alpine 3.21 runtime, non-root user, port 5230, multi-arch amd64/arm64/arm/v7.