memos/CLAUDE.md

CLAUDE.md

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)

# 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)

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
• /plugin/ - Modular plugins (S3 storage, OAuth, webhooks, etc.)

Frontend Structure

• /web/src/ - React/TypeScript application
• /web/src/components/ - Reusable UI components with shadcn/ui
• /web/src/pages/ - Page-level components
• /web/src/store/ - MobX state management
• /web/src/types/ - TypeScript type definitions generated from protobuf

Key Architecture Patterns

Server Architecture

• Protocol Multiplexing: Single port serves both HTTP and gRPC via cmux
• gRPC-first: Core APIs defined in protobuf, REST via grpc-gateway
• Layered: Router → Service → Store → Database
• Middleware: Authentication, logging, CORS handled via interceptors

Database Layer

• Multi-database: Unified interface for SQLite, PostgreSQL, MySQL
• Migration System: Version-based schema migrations in /store/migration/
• Driver Pattern: /store/db/{sqlite,postgres,mysql}/ with common interface
• Caching: Built-in cache layer for workspace settings, users, user settings

Authentication & Security

• JWT-based: Secret key generated per workspace
• gRPC Interceptors: Authentication middleware for all API calls
• Context Propagation: User context flows through request lifecycle
• Development vs Production: Different secret handling based on mode

Database Operations

Supported Databases

• SQLite (default): --driver sqlite --data ./data
• PostgreSQL: --driver postgres --dsn "postgres://..."
• MySQL: --driver mysql --dsn "user:pass@tcp(host:port)/db"

Migration System

• Database schema managed via /store/migration/{sqlite,postgres,mysql}/
• Automatic migration on startup via store.Migrate(ctx)
• Version-based migration files (e.g., 0.22/00__memo_tags.sql)

Testing Approach

Backend Testing

• Store Tests: /store/test/*_test.go with in-memory SQLite
• API Tests: /server/router/api/v1/test/*_test.go with full service setup
• Test Helpers:
  • NewTestingStore() for isolated database testing
  • NewTestService() for API integration testing
• Test Patterns: Context-based authentication, proper cleanup, realistic data

Frontend Testing

• Currently relies on TypeScript compilation and ESLint
• No dedicated test framework configured

Running Tests

# All tests
go test -v ./...

# Specific packages
go test -v ./store/test/
go test -v ./server/router/api/v1/test/

# With coverage
go test -cover ./...

Development Modes

Production Mode

go run ./bin/memos/main.go --mode prod --port 5230

• Uses workspace-generated secret key
• Serves built frontend from /server/router/frontend/dist/
• Optimized for deployment

Development Mode

go run ./bin/memos/main.go --mode dev --port 8081

• Fixed secret key "usememos"
• Enables debugging features
• Separate frontend development server recommended

Demo Mode

go run ./bin/memos/main.go --mode demo

• Specialized configuration for demonstration purposes

Key Configuration

Environment Variables

All CLI flags can be set via environment variables with MEMOS_ prefix:

• MEMOS_MODE - Server mode (dev/prod/demo)
• MEMOS_PORT - Server port
• MEMOS_DATA - Data directory
• MEMOS_DRIVER - Database driver
• MEMOS_DSN - Database connection string
• MEMOS_INSTANCE_URL - Public instance URL

Runtime Configuration

• Profile: /internal/profile/ handles configuration validation
• Secrets: Auto-generated workspace secret in production
• Data Directory: Configurable storage location for SQLite and assets

Frontend Technology Stack

Core Framework

• React 18 with TypeScript
• Vite for build tooling and development server
• React Router for navigation
• MobX for state management

UI Components

• Radix UI primitives for accessibility
• Tailwind CSS for styling with custom themes
• Lucide React for icons
• shadcn/ui component patterns

Key Libraries

• dayjs for date manipulation
• highlight.js for code syntax highlighting
• katex for math rendering
• mermaid for diagram rendering
• react-leaflet for maps
• i18next for internationalization

Protocol Buffer Workflow

Code Generation

• Source: /proto/api/v1/*.proto and /proto/store/*.proto
• Generated: /proto/gen/ for Go, /web/src/types/proto/ for TypeScript
• Build Tool: Buf for protobuf compilation
• API Docs: Generated swagger at /proto/gen/apidocs.swagger.yaml

API Design

• gRPC services in /proto/api/v1/
• Resource-oriented design (User, Memo, Attachment, etc.)
• REST gateway auto-generated from protobuf annotations

File Organization Principles

Backend

• Domain-driven: Each entity (user, memo, attachment) has dedicated files
• Layered: Clear separation between API, business logic, and data layers
• Database-agnostic: Common interfaces with driver-specific implementations

Frontend

• Component-based: Reusable components in /components/
• Feature-based: Related functionality grouped together
• Type-safe: Strong TypeScript integration with generated protobuf types

Common Development Workflows

Adding New API Endpoint

1. Define service method in /proto/api/v1/{service}.proto
2. Generate code: buf generate
3. Implement service method in /server/router/api/v1/{service}_service.go
4. Add any required store methods in /store/{entity}.go
5. Update database layer if needed in /store/db/{driver}/{entity}.go

Database Schema Changes

1. Create migration file in /store/migration/{driver}/{version}/
2. Update store interface in /store/{entity}.go
3. Implement in each database driver
4. Update protobuf if external API changes needed

Frontend Component Development

1. Create component in /web/src/components/
2. Follow existing patterns for styling and state management
3. Use TypeScript for type safety
4. Import and use in pages or other components