This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
**Memos** is a modern, open-source, self-hosted knowledge management and note-taking platform designed for privacy-conscious users and organizations. It provides a lightweight yet powerful solution for capturing, organizing, and sharing thoughts with comprehensive Markdown support and cross-platform accessibility.
### Key Technologies
## Project Overview
-**Backend**: Go 1.24 with gRPC and Protocol Buffers
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.
-**Frontend**: React 18 with TypeScript, Vite, and Tailwind CSS
-**Database**: SQLite (default), MySQL, PostgreSQL support
-**API**: RESTful HTTP/gRPC with grpc-gateway
-**Authentication**: JWT-based with OAuth2 providers
## Architecture Overview
## Development Commands
### Backend Structure
### Backend (Go)
```bash
# Run in development mode
go run ./bin/memos/main.go --mode dev --port 8081
```text
# Build binary
server/
go build -o ./build/memos ./bin/memos/main.go
├── router/
# OR use build script
│ ├── api/v1/ # API v1 services and handlers
./scripts/build.sh
│ ├── frontend/ # Static frontend assets
│ └── rss/ # RSS feed generation
├── runner/ # Background job runners
└── profiler/ # Performance profiling
```
### Protocol Buffers & API
# Run tests
go test-v ./...
```text
go test-cover ./...
proto/
├── api/v1/ # Public API definitions
│ ├── user_service.proto
│ ├── workspace_service.proto
│ ├── shortcut_service.proto
│ ├── idp_service.proto
│ └── webhook_service.proto
└── store/ # Internal data structures
├── workspace_setting.proto
├── user_setting.proto
└── ...
```
### Data Layer
# Run specific test packages
go test-v ./store/test/
```text
go test-v ./server/router/api/v1/test/
store/
├── db/ # Database drivers
│ ├── sqlite/
│ ├── mysql/
│ └── postgres/
├── migration/ # Database migrations
├── cache/ # Caching layer
└── test/ # Test utilities
```
```
## Recent Major Refactoring: Google AIP Compliance
### Frontend (React/TypeScript)
```bash
### Overview
cd web/
We recently completed a comprehensive refactoring to align the API with Google API Improvement Proposals (AIP) for resource-oriented API design. This involved updating protocol buffers, backend services, and frontend TypeScript code.
### Key Changes Made
#### 1. Protocol Buffer Refactoring
-**Resource Patterns**: Implemented standard resource naming (e.g., `users/{user}`, `workspace/settings/{setting}`)
-**Field Behaviors**: Added proper field annotations (`REQUIRED`, `OUTPUT_ONLY`, `IMMUTABLE`)
-**HTTP Annotations**: Updated REST mappings to follow RESTful conventions
-**Service Consolidation**: Merged `workspace_setting_service.proto` into `workspace_service.proto`
#### 2. Backend Service Updates
-**Resource Name Handling**: Added robust parsing for resource names
-**Method Signatures**: Updated to use resource names instead of raw IDs
-**Error Handling**: Improved error responses with proper gRPC status codes
-**Permission Checks**: Enhanced authorization based on user roles
#### 3. Frontend TypeScript Migration
# Development server (http://localhost:3001)
pnpm dev
-**Resource Name Utilities**: Helper functions for extracting IDs from resource names
# Build for production
-**State Management**: Updated MobX stores to use new resource formats
pnpm build
-**Component Updates**: React components now handle new API structures
-**Type Safety**: Enhanced TypeScript definitions for better type checking
## Development Workflow
# Build for release (outputs to server/router/frontend/dist)
pnpm release
### Code Quality Standards
# Lint and type check
pnpm lint
```
-**golangci-lint**: Comprehensive linting with 15+ linters enabled
### Full Development Setup
-**Protocol Buffer Generation**: `buf generate` for type-safe API generation
1.**Backend**: `go run ./bin/memos/main.go --mode dev --port 8081`
