Memos pairs a Go backend with a Vite React client. The CLI entry in `bin/memos` boots the HTTP server under `server`, backed by shared domain logic in `internal` and persistence adapters in `store`. Frontend code lives in `web/src` with static assets in `web/public`; `pnpm release` publishes bundles into `server/router/frontend/dist`. API schemas sit in `proto/` (Buf-managed), extensions in `plugin/`, deployment helpers in `scripts/`, and sample SQLite databases in `build/`.
## Build, Test, and Development Commands
-`go run ./bin/memos --mode dev --port 8081` – start the backend with the default SQLite store.
-`go build ./bin/memos` – compile the backend binary.
-`go test ./...` – run Go unit and store tests.
-`cd web && pnpm install` – install frontend dependencies.
-`cd web && pnpm dev` – start the Vite dev server with hot reload.
-`cd web && pnpm build` – emit production assets; `pnpm release` copies them to the Go server.
-`cd web && pnpm lint` – type-check and enforce ESLint/Prettier.
## Coding Style & Naming Conventions
Go code must stay `gofmt`-clean (tabs, import grouping) and keep packages lowercase. Prefer context-aware functions and wrap errors with `%w` when bubbling them. Frontend components use PascalCase filenames, hooks stay in camelCase, and Tailwind utilities live alongside components. Prettier (see `web/.prettierrc.js`) governs formatting and import ordering—skip manual tweaks. Update translation keys in `web/src/i18n` whenever UI text changes.
## Testing Guidelines
Place Go tests in `_test.go` siblings and prefer table-driven cases for store behaviours and REST handlers. Run `go test ./...` before pushing and extend coverage when touching migrations or API contracts. The frontend currently leans on linting and manual checks—attach before/after screenshots for UI work and add Go smoke tests when endpoints change.
## Commit & Pull Request Guidelines
Follow the Conventional Commit prefixes visible in history (`feat:`, `fix:`, `chore:`) and keep scopes concise (`feat(server): ...`). Reference linked issues in the body and describe observed impact plus testing performed. Pull requests should summarize the change, note schema or config migrations, include screenshots for UI updates, and flag follow-up tasks so reviewers can plan rollout.
## Security & Configuration Notes
Backend flags and `MEMOS_*` environment variables configure ports, database drivers, and instance URLs—mirror production defaults for security-sensitive work. Review `SECURITY.md` before handling vulnerability fixes and avoid committing secrets; keep `.env.local` files out of version control.
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Project Overview
Memos is a self-hosted note-taking and knowledge management platform with a Go backend and React/TypeScript frontend. The architecture follows clean separation of concerns with gRPC APIs, REST gateway, and database abstraction.
## Development Commands
### Backend (Go)
```bash
# Run in development mode
go run ./bin/memos/main.go --mode dev --port 8081
# Build binary
go build -o ./build/memos ./bin/memos/main.go
# OR use build script
./scripts/build.sh
# Run tests
go test-v ./...
go test-cover ./...
# Run specific test packages
go test-v ./store/test/
go test-v ./server/router/api/v1/test/
```
### Frontend (React/TypeScript)
```bash
cd web/
# Development server (http://localhost:3001)
pnpm dev
# Build for production
pnpm build
# Build for release (outputs to server/router/frontend/dist)
pnpm release
# Lint and type check
pnpm lint
```
### Full Development Setup
1.**Backend**: `go run ./bin/memos/main.go --mode dev --port 8081`
2.**Frontend**: `cd web && pnpm dev`
3.**Access**: Backend API at `http://localhost:8081`, Frontend at `http://localhost:3001`
## Architecture Overview
### Backend Structure
-**`/bin/memos/main.go`** - Application entrypoint with CLI and server initialization
-**`/server/`** - HTTP/gRPC server with Echo framework and cmux for protocol multiplexing
-**`/server/router/api/v1/`** - gRPC services with REST gateway via grpc-gateway
-**`/store/`** - Data access layer with multi-database support (SQLite/PostgreSQL/MySQL)
-**`/store/db/`** - Database-specific implementations with shared interface
-**`/proto/`** - Protocol buffer definitions for APIs and data models
-**`/internal/`** - Shared utilities, profile management, and version handling
