feat: init serena memory system & add memories (#2902)

2025-11-06 14:22:40 +08:00 · 2025-11-06 14:22:40 +08:00 · 496b15048a
parent de0360b118
commit 496b15048a
14 changed files with 842 additions and 1 deletions
--- a/.gitignore
+++ b/.gitignore
@ -91,6 +91,8 @@ hs_err_pid*
 hugegraph-server/hugegraph-dist/docker/data/

 # AI-IDE prompt files (We only keep AGENTS.md, other files could soft-linked it when needed)
+# Serena MCP memories
+.serena/
 # Claude Projects
 CLAUDE.md
 CLAUDE_*.md
--- a/.licenserc.yaml
+++ b/.licenserc.yaml
@ -59,6 +59,7 @@ header: # `header` section is configurations for source codes license header.
    - 'LICENSE'
    - 'NOTICE'
    - 'DISCLAIMER'
+    - '.serena/**'
    - '**/*.versionsBackup'
    - '**/*.versionsBackup'
    - '**/*.proto'
--- a/.serena/.gitignore
+++ b/.serena/.gitignore
@ -0,0 +1 @@
+/cache
--- a/.serena/memories/architecture_and_modules.md
+++ b/.serena/memories/architecture_and_modules.md
@ -0,0 +1,99 @@
+# Architecture and Module Structure
+
+## Three-Tier Architecture
+
+### 1. Client Layer
+- Gremlin/Cypher query interfaces
+- REST API endpoints
+- Multiple client language bindings
+
+### 2. Server Layer (hugegraph-server)
+- **REST API Layer** (hugegraph-api): GraphAPI, SchemaAPI, GremlinAPI, CypherAPI, AuthAPI
+- **Graph Engine Layer** (hugegraph-core): Schema management, traversal optimization, task scheduling
+- **Backend Interface**: Abstraction over storage backends
+
+### 3. Storage Layer
+- Pluggable backend implementations
+- Each backend extends `hugegraph-core` abstractions
+- Implements `BackendStore` interface
+
+## Multi-Module Structure
+
+The project consists of 7 main modules:
+
+### 1. hugegraph-server (13 submodules)
+Core graph engine, REST APIs, and backend implementations:
+- `hugegraph-core` - Core graph engine and abstractions
+- `hugegraph-api` - REST API implementations (includes OpenCypher in `opencypher/`)
+- `hugegraph-dist` - Distribution packaging and scripts
+- `hugegraph-test` - Test suites (unit, core, API, TinkerPop)
+- `hugegraph-example` - Example code
+- Backend implementations:
+  - `hugegraph-rocksdb` (default)
+  - `hugegraph-hstore` (distributed)
+  - `hugegraph-hbase`
+  - `hugegraph-mysql`
+  - `hugegraph-postgresql`
+  - `hugegraph-cassandra`
+  - `hugegraph-scylladb`
+  - `hugegraph-palo`
+
+### 2. hugegraph-pd (8 submodules)
+Placement Driver for distributed deployments (meta server):
+- `hg-pd-core` - Core PD logic
+- `hg-pd-service` - PD service implementation
+- `hg-pd-client` - Client library
+- `hg-pd-common` - Shared utilities
+- `hg-pd-grpc` - gRPC protocol definitions (auto-generated)
+- `hg-pd-cli` - Command line interface
+- `hg-pd-dist` - Distribution packaging
+- `hg-pd-test` - Test suite
+
+### 3. hugegraph-store (9 submodules)
+Distributed storage backend with RocksDB and Raft:
+- `hg-store-core` - Core storage logic
+- `hg-store-node` - Storage node implementation
+- `hg-store-client` - Client library
+- `hg-store-common` - Shared utilities
+- `hg-store-grpc` - gRPC protocol definitions (auto-generated)
+- `hg-store-rocksdb` - RocksDB integration
+- `hg-store-cli` - Command line interface
+- `hg-store-dist` - Distribution packaging
+- `hg-store-test` - Test suite
+
+### 4. hugegraph-commons
+Shared utilities across modules:
+- Locks and concurrency utilities
+- Configuration management
+- RPC framework components
+
+### 5. hugegraph-struct
+Data structure definitions shared between modules.
+**Important**: Must be built before PD and Store modules.
+
+### 6. install-dist
+Distribution packaging and release management:
+- License and NOTICE files
+- Dependency management scripts
+- Release documentation
+
+### 7. hugegraph-cluster-test
+Cluster integration tests for distributed deployments
+
+## Cross-Module Dependencies
+
+```
+hugegraph-commons → (shared by all modules)
+hugegraph-struct → hugegraph-pd + hugegraph-store
+hugegraph-core → (extended by all backend implementations)
+```
+
+## Distributed Architecture (Optional)
+
+For production distributed deployments:
+- **hugegraph-pd**: Service discovery, partition management, metadata
+- **hugegraph-store**: Distributed storage with Raft (3+ nodes)
+- **hugegraph-server**: Multiple server instances (3+)
+- Communication: All use gRPC with Protocol Buffers
+
+**Status**: Distributed components (PD + Store) are in BETA
--- a/.serena/memories/code_style_and_conventions.md
+++ b/.serena/memories/code_style_and_conventions.md
@ -0,0 +1,92 @@
+# Code Style and Conventions
+
+## Code Style Configuration
+- **Import**: Use `hugegraph-style.xml` in your IDE (IntelliJ IDEA recommended)
+- **EditorConfig**: `.editorconfig` file defines style rules (validated in CI)
+- **Checkstyle**: `style/checkstyle.xml` defines additional rules
+
+## Core Style Rules (from .editorconfig)
+
+### General
+- Charset: UTF-8
+- End of line: LF (Unix-style)
+- Insert final newline: true
+- Max line length: 100 characters (120 for XML)
+- Visual guides at column 100
+
+### Java Files
+- Indent: 4 spaces (not tabs)
+- Continuation indent: 8 spaces
+- Wrap on typing: true
+- Wrap long lines: true
+
+### Import Organization
+```
+$*
+|
+java.**
+|
+javax.**
+|
+org.**
+|
+com.**
+|
+*
+```
+- Class count to use import on demand: 100
+- Names count to use import on demand: 100
+
+### Formatting Rules
+- Line comments not at first column
+- Align multiline: chained methods, parameters in calls, binary operations, assignments, ternary, throws, extends, array initializers
+- Wrapping: normal (wrap if necessary)
+- Brace forcing:
+  - if: if_multiline
+  - do-while: always
+  - while: if_multiline
+  - for: if_multiline
+- Enum constants: split_into_lines
+
+### Blank Lines
+- Max blank lines in declarations: 1
+- Max blank lines in code: 1
+- Blank lines between package declaration and header: 1
+- Blank lines before right brace: 1
+- Blank lines around class: 1
+- Blank lines after class header: 1
+
+### Documentation
+- Add `<p>` tag on empty lines: true
+- Do not wrap if one line: true
+- Align multiline annotation parameters: true
+
+### XML Files
+- Indent: 4 spaces
+- Max line length: 120
+- Text wrap: off
+- Space inside empty tag: true
+
+### Maven
+- Compiler source/target: Java 11
+- Max compiler errors: 500
+- Compiler args: `-Xlint:unchecked`
+- Source encoding: UTF-8
+
+## Lombok Usage
+- Version: 1.18.30
+- Scope: provided
+- Optional: true
+
+## License Headers
+- All source files MUST include Apache Software License header
+- Validated by apache-rat-plugin and skywalking-eyes
+- Exclusions defined in pom.xml (line 171-221)
+- gRPC generated code excluded from license check
+
+## Naming Conventions
+- Package names: lowercase, dot-separated (e.g., org.apache.hugegraph)
+- Class names: PascalCase
+- Method names: camelCase
+- Constants: UPPER_SNAKE_CASE
+- Variables: camelCase
--- a/.serena/memories/ecosystem_and_related_projects.md
+++ b/.serena/memories/ecosystem_and_related_projects.md
@ -0,0 +1,63 @@
+# HugeGraph Ecosystem and Related Projects
+
+## Core Repository (This Project)
+**Repository**: apache/hugegraph (server)
+**Purpose**: Core graph database engine (OLTP)
+
+## Related Repositories
+
+### 1. hugegraph-toolchain
+**Repository**: https://github.com/apache/hugegraph-toolchain
+**Components**:
+- **hugegraph-loader**: Bulk data loading tool
+- **hugegraph-hubble**: Web-based visualization dashboard
+- **hugegraph-tools**: Command-line utilities
+- **hugegraph-client**: Java client SDK
+
+### 2. hugegraph-computer
+**Repository**: https://github.com/apache/hugegraph-computer
+**Purpose**: Distributed graph computing framework (OLAP)
+**Features**: PageRank, Connected Components, Shortest Path, Community Detection
+
+### 3. hugegraph-ai
+**Repository**: https://github.com/apache/incubator-hugegraph-ai
+**Purpose**: Graph AI, LLM, and Knowledge Graph integration
+**Features**: Graph-enhanced LLM, KG construction, Graph RAG, NL to Gremlin/Cypher
+
+### 4. hugegraph-website
+**Repository**: https://github.com/apache/hugegraph-doc
+**Purpose**: Official documentation and website
+**URL**: https://hugegraph.apache.org/
+
+## Integration Points
+
+### Data Pipeline
+```
+Data Sources → hugegraph-loader → hugegraph-server
+                                        ↓
+                    ┌───────────────────┼───────────────────┐
+                    ↓                   ↓                   ↓
+            hugegraph-hubble    hugegraph-computer   hugegraph-ai
+            (Visualization)      (Analytics)         (AI/ML)
+```
+
+## External Integrations
+
+### Big Data Platforms
+- Apache Flink, Apache Spark, HDFS
+
+### Storage Backends
+- RocksDB (default), HBase, Cassandra, ScyllaDB, MySQL, PostgreSQL
+
+### Query Languages
+- Gremlin (Apache TinkerPop), Cypher (OpenCypher), REST API
+
+## Version Compatibility
+- Server: 1.7.0
+- TinkerPop: 3.5.1
+- Java: 11+ required
+
+## Use Cases
+- Social networks, Fraud detection, Recommendation systems
+- Knowledge graphs, Network analysis, Supply chain management
+- IT operations, Bioinformatics
--- a/.serena/memories/implementation_patterns_and_guidelines.md
+++ b/.serena/memories/implementation_patterns_and_guidelines.md
@ -0,0 +1,104 @@
+# Implementation Patterns and Guidelines
+
+## Backend Development
+
+### Backend Architecture Pattern
+- All backends extend abstractions from `hugegraph-server/hugegraph-core`
+- Implement the `BackendStore` interface
+- Each backend is a separate Maven module under `hugegraph-server/`
+- Backend selection configured in `hugegraph.properties` via `backend` property
+
+### Available Backends
+- **RocksDB** (default, embedded): `hugegraph-rocksdb`
+- **HStore** (distributed, production): `hugegraph-hstore`
+- **Legacy** (≤1.5.0): MySQL, PostgreSQL, Cassandra, ScyllaDB, HBase, Palo
+
+### Backend Testing Profiles
+- `memory`: In-memory backend for fast unit tests
+- `rocksdb`: RocksDB for realistic local tests
+- `hbase`: HBase for distributed scenarios
+- `hstore`: HStore for production-like distributed tests
+
+## gRPC Protocol Development
+
+### Protocol Buffer Definitions
+- PD protos: `hugegraph-pd/hg-pd-grpc/src/main/proto/`
+- Store protos: `hugegraph-store/hg-store-grpc/src/main/proto/`
+
+### Code Generation
+When modifying `.proto` files:
+1. Run `mvn clean compile` to regenerate gRPC stubs
+2. Generated Java code goes to `*/grpc/` packages
+3. Output location: `target/generated-sources/protobuf/`
+4. Generated files excluded from Apache RAT checks
+5. All inter-service communication uses gRPC
+
+## Authentication System
+
+### Default State
+- Authentication **disabled by default**
+- Enable via `bin/enable-auth.sh` or configuration
+- **Required for production deployments**
+
+### Implementation Location
+`hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/auth/`
+
+### Multi-Level Security Model
+- Users, Groups, Projects, Targets, Access control
+
+## TinkerPop Integration
+
+### Compliance
+- Full Apache TinkerPop 3 implementation
+- Custom optimization strategies
+- Supports both Gremlin and OpenCypher query languages
+
+### Query Language Support
+- **Gremlin**: Native via TinkerPop integration
+- **OpenCypher**: Implementation in `hugegraph-api/opencypher/`
+
+## Testing Patterns
+
+### Test Suite Organization
+- **UnitTestSuite**: Pure unit tests, no external dependencies
+- **CoreTestSuite**: Core functionality tests with backend
+- **ApiTestSuite**: REST API integration tests
+- **StructureStandardTest**: TinkerPop structure compliance
+- **ProcessStandardTest**: TinkerPop process compliance
+
+### Backend Selection in Tests
+Use Maven profiles:
+```bash
+-P core-test,memory      # Fast in-memory
+-P core-test,rocksdb     # Persistent local
+-P api-test,rocksdb      # API with persistent backend
+```
+
+## Distribution and Packaging
+
+### Creating Distribution
+```bash
+mvn clean package -DskipTests
+```
+Output: `install-dist/target/hugegraph-<version>.tar.gz`
+
+## Code Organization
+
+### Package Structure
+```
+org.apache.hugegraph
+├── backend/        # Backend implementations
+├── api/           # REST API endpoints
+├── core/          # Core graph engine
+├── schema/        # Schema definitions
+├── traversal/     # Traversal and query processing
+├── task/          # Background tasks
+├── auth/          # Authentication/authorization
+└── util/          # Utilities
+```
+
+### Module Dependencies
+- Commons is shared by all modules
+- Struct must be built before PD and Store
+- Backend modules depend on core
+- Test module depends on all server modules
--- a/.serena/memories/key_file_locations.md
+++ b/.serena/memories/key_file_locations.md
@ -0,0 +1,87 @@
+# Key File and Directory Locations
+
+## Project Root
+The project root contains the multi-module Maven structure.
+
+## Configuration Files
+
+### Build Configuration
+- `pom.xml` - Root Maven POM (multi-module)
+- `.editorconfig` - Code style rules
+- `style/checkstyle.xml` - Checkstyle rules
+- `.licenserc.yaml` - License checker config
+
+### Documentation
+- `README.md` - Project overview
+- `BUILDING.md` - Build instructions
+- `CONTRIBUTING.md` - Contribution guide
+- `AGENTS.md` - AI agent development guide
+- `LICENSE` - Apache License 2.0
+- `NOTICE` - Copyright notices
+
+## Server Module (hugegraph-server)
+
+### Core Implementation
+- `hugegraph-core/src/main/java/org/apache/hugegraph/` - Core engine
+  - `backend/` - Backend interface
+  - `schema/` - Schema management
+  - `traversal/` - Query processing
+  - `task/` - Background tasks
+
+### API Layer
+- `hugegraph-api/src/main/java/org/apache/hugegraph/api/` - REST APIs
+  - `graph/` - GraphAPI
+  - `schema/` - SchemaAPI
+  - `gremlin/` - GremlinAPI
+  - `cypher/` - CypherAPI
+  - `auth/` - AuthAPI
+  - `opencypher/` - OpenCypher implementation
+
+### Backend Implementations
+- `hugegraph-rocksdb/` - RocksDB backend (default)
+- `hugegraph-hstore/` - HStore distributed backend
+- `hugegraph-hbase/` - HBase backend
+- `hugegraph-mysql/` - MySQL backend
+- `hugegraph-postgresql/` - PostgreSQL backend
+- `hugegraph-cassandra/` - Cassandra backend
+- `hugegraph-scylladb/` - ScyllaDB backend
+- `hugegraph-palo/` - Palo backend
+
+### Distribution and Scripts
+- `hugegraph-dist/src/assembly/static/` - Distribution files
+  - `bin/` - Shell scripts (init-store.sh, start-hugegraph.sh, stop-hugegraph.sh, etc.)
+  - `conf/` - Configuration files (hugegraph.properties, rest-server.properties, gremlin-server.yaml, log4j2.xml)
+  - `lib/` - JAR dependencies
+  - `logs/` - Log files
+
+### Testing
+- `hugegraph-test/src/main/java/org/apache/hugegraph/` - Test suites
+  - `unit/` - Unit tests
+  - `core/` - Core functionality tests
+  - `api/` - API integration tests
+  - `tinkerpop/` - TinkerPop compliance tests
+
+## PD Module (hugegraph-pd)
+- `hg-pd-core/` - Core PD logic
+- `hg-pd-service/` - Service implementation
+- `hg-pd-client/` - Client library
+- `hg-pd-grpc/src/main/proto/` - Protocol definitions
+- `hg-pd-dist/src/assembly/static/` - Distribution files
+
+## Store Module (hugegraph-store)
+- `hg-store-core/` - Core storage logic
+- `hg-store-node/` - Storage node
+- `hg-store-client/` - Client library
+- `hg-store-grpc/src/main/proto/` - Protocol definitions
+- `hg-store-dist/src/assembly/static/` - Distribution files
+
+## Commons Module (hugegraph-commons)
+- Shared utilities, RPC framework
+
+## Struct Module (hugegraph-struct)
+- Data structure definitions (must be built before PD and Store)
+
+## Distribution Module (install-dist)
+- `release-docs/` - LICENSE, NOTICE, licenses/
+- `scripts/dependency/` - Dependency management scripts
+- `target/` - Build output (hugegraph-<version>.tar.gz)
--- a/.serena/memories/project_overview.md
+++ b/.serena/memories/project_overview.md
@ -0,0 +1,35 @@
+# Apache HugeGraph Project Overview
+
+## Project Purpose
+Apache HugeGraph is a fast-speed and highly-scalable graph database that supports billions of vertices and edges (10+ billion scale). It is designed for OLTP workloads with excellent performance and scalability.
+
+## Key Capabilities
+- Graph database compliant with Apache TinkerPop 3 framework
+- Supports both Gremlin and Cypher query languages
+- Schema metadata management (VertexLabel, EdgeLabel, PropertyKey, IndexLabel)
+- Multi-type indexes (exact, range, complex conditions)
+- Pluggable backend storage architecture
+- Integration with big data platforms (Flink/Spark/HDFS)
+- Complete graph ecosystem (computing, visualization, AI/ML)
+
+## Technology Stack
+- **Language**: Java 11+ (required)
+- **Build Tool**: Apache Maven 3.5+ (required)
+- **Graph Framework**: Apache TinkerPop 3.5.1
+- **RPC**: gRPC with Protocol Buffers
+- **Storage Backends**: 
+  - RocksDB (default, embedded)
+  - HStore (distributed, production)
+  - Legacy (≤1.5.0): MySQL, PostgreSQL, Cassandra, ScyllaDB, HBase, Palo
+
+## Project Version
+- Current version: 1.7.0 (managed via `${revision}` property)
+- Version management uses Maven flatten plugin for CI-friendly versioning
+
+## License
+- Apache License 2.0
+- All code must include Apache license headers
+- Third-party dependencies require proper license documentation
+
+## Repository Structure
+This is a multi-module Maven project
--- a/.serena/memories/suggested_commands.md
+++ b/.serena/memories/suggested_commands.md
@ -0,0 +1,131 @@
+# Suggested Development Commands
+
+## Quick Reference
+
+### Prerequisites Check
+```bash
+java -version        # Must be 11+
+mvn -version         # Must be 3.5+
+```
+
+### Build Commands
+```bash
+# Full build without tests (fastest)
+mvn clean install -DskipTests
+
+# Full build with all tests
+mvn clean install
+
+# Build specific module (e.g., server)
+mvn clean install -pl hugegraph-server -am -DskipTests
+
+# Compile only
+mvn clean compile -U -Dmaven.javadoc.skip=true -ntp
+
+# Build distribution package
+mvn clean package -DskipTests
+# Output: install-dist/target/hugegraph-<version>.tar.gz
+```
+
+### Testing Commands
+```bash
+# Unit tests (memory backend)
+mvn test -pl hugegraph-server/hugegraph-test -am -P unit-test,memory
+
+# Core tests with specific backend
+mvn test -pl hugegraph-server/hugegraph-test -am -P core-test,memory
+mvn test -pl hugegraph-server/hugegraph-test -am -P core-test,rocksdb
+mvn test -pl hugegraph-server/hugegraph-test -am -P core-test,hbase
+
+# API tests
+mvn test -pl hugegraph-server/hugegraph-test -am -P api-test,rocksdb
+
+# TinkerPop compliance tests (release branches)
+mvn test -pl hugegraph-server/hugegraph-test -am -P tinkerpop-structure-test,memory
+mvn test -pl hugegraph-server/hugegraph-test -am -P tinkerpop-process-test,memory
+
+# Run single test class
+mvn test -pl hugegraph-server/hugegraph-test -am -P core-test,memory -Dtest=YourTestClass
+
+# PD module tests (build struct first)
+mvn install -pl hugegraph-struct -am -DskipTests
+mvn test -pl hugegraph-pd/hg-pd-test -am
+
+# Store module tests (build struct first)
+mvn install -pl hugegraph-struct -am -DskipTests
+mvn test -pl hugegraph-store/hg-store-test -am
+```
+
+### Code Quality & Validation
+```bash
+# License header check (Apache RAT)
+mvn apache-rat:check -ntp
+
+# Code style check (EditorConfig)
+mvn editorconfig:check
+
+# Compile with warnings
+mvn clean compile -Dmaven.javadoc.skip=true
+```
+
+### Server Operations
+```bash
+# Scripts location: hugegraph-server/hugegraph-dist/src/assembly/static/bin/
+
+# Initialize storage backend
+bin/init-store.sh
+
+# Start HugeGraph server
+bin/start-hugegraph.sh
+
+# Stop HugeGraph server
+bin/stop-hugegraph.sh
+
+# Start Gremlin console
+bin/gremlin-console.sh
+
+# Enable authentication
+bin/enable-auth.sh
+
+# Dump effective configuration
+bin/dump-conf.sh
+
+# Monitor server
+bin/monitor-hugegraph.sh
+```
+
+### Git Operations (macOS/Darwin)
+```bash
+# View git log (avoid pager)
+git --no-pager log -n 20 --oneline
+
+# View git diff (avoid pager)
+git --no-pager diff
+
+# Check git status
+git status
+```
+
+### Docker Commands (Test/Dev)
+```bash
+# Start HugeGraph in Docker (RocksDB backend)
+docker run -itd --name=graph -p 8080:8080 hugegraph/hugegraph:1.5.0
+
+# Start with preloaded sample graph
+docker run -itd --name=graph -e PRELOAD=true -p 8080:8080 hugegraph/hugegraph:1.5.0
+```
+
+### Distributed Components Build (BETA)
+```bash
+# 1. Build hugegraph-struct (required dependency)
+mvn install -pl hugegraph-struct -am -DskipTests
+
+# 2. Build hugegraph-pd (Placement Driver)
+mvn clean package -pl hugegraph-pd -am -DskipTests
+
+# 3. Build hugegraph-store (distributed storage)
+mvn clean package -pl hugegraph-store -am -DskipTests
+
+# 4. Build hugegraph-server with HStore backend
+mvn clean package -pl hugegraph-server -am -DskipTests
+```
--- a/.serena/memories/task_completion_checklist.md
+++ b/.serena/memories/task_completion_checklist.md
@ -0,0 +1,139 @@
+# Task Completion Checklist
+
+When completing a coding task, follow these steps to ensure quality and compliance:
+
+## 1. Code Quality Checks (MANDATORY)
+
+### License Header Check
+Run Apache RAT to verify all files have proper license headers:
+```bash
+mvn apache-rat:check -ntp
+```
+Fix any violations by adding the Apache license header.
+
+### Code Style Check
+Run EditorConfig validation:
+```bash
+mvn editorconfig:check
+```
+Fix violations according to `.editorconfig` rules.
+
+### Compilation Check
+Compile with warnings enabled:
+```bash
+mvn clean compile -Dmaven.javadoc.skip=true
+```
+Resolve all compiler warnings, especially unchecked operations.
+
+## 2. Testing (REQUIRED)
+
+### Determine Test Scope
+Check project README or ask user for test commands. Common patterns:
+
+#### Server Module Tests
+- Unit tests:
+```bash
+mvn test -pl hugegraph-server/hugegraph-test -am -P unit-test,memory
+```
+- Core tests (choose backend):
+```bash
+mvn test -pl hugegraph-server/hugegraph-test -am -P core-test,memory
+mvn test -pl hugegraph-server/hugegraph-test -am -P core-test,rocksdb
+```
+- API tests:
+```bash
+mvn test -pl hugegraph-server/hugegraph-test -am -P api-test,rocksdb
+```
+
+#### PD Module Tests
+```bash
+# Build struct dependency first
+mvn install -pl hugegraph-struct -am -DskipTests
+# Run PD tests
+mvn test -pl hugegraph-pd/hg-pd-test -am
+```
+
+#### Store Module Tests
+```bash
+# Build struct dependency first
+mvn install -pl hugegraph-struct -am -DskipTests
+# Run Store tests
+mvn test -pl hugegraph-store/hg-store-test -am
+```
+
+### Run Appropriate Tests
+Execute tests relevant to your changes:
+- For bug fixes: run existing tests to verify fix
+- For new features: write and run new tests
+- For refactoring: run all affected module tests
+
+## 3. Dependencies Management
+
+If adding new third-party dependencies:
+
+1. Add license file to `install-dist/release-docs/licenses/`
+2. Declare dependency in `install-dist/release-docs/LICENSE`
+3. Append NOTICE (if exists) to `install-dist/release-docs/NOTICE`
+4. Update dependency list:
+```bash
+./install-dist/scripts/dependency/regenerate_known_dependencies.sh
+```
+Or manually update `install-dist/scripts/dependency/known-dependencies.txt`
+
+## 4. Build Verification
+
+Build the affected module(s) with tests:
+```bash
+mvn clean install -pl <module> -am
+```
+
+## 5. Documentation (if applicable)
+
+- Update JavaDoc for public APIs
+- Update README if adding user-facing features
+- Update AGENTS.md if adding dev-facing information
+
+## 6. Commit Preparation
+
+### NEVER Commit Unless Explicitly Asked
+- Do NOT auto-commit changes
+- Only commit when user explicitly requests it
+- This is CRITICAL to avoid surprising users
+
+### When Asked to Commit
+- Write clear commit messages:
+```
+Fix bug: <brief description>
+
+fix #ISSUE_ID
+```
+- Include issue ID if available
+- Describe what and how the change works
+
+## 7. Pre-PR Checklist
+
+Before creating a Pull Request, ensure:
+- [ ] All license checks pass
+- [ ] All code style checks pass
+- [ ] All relevant tests pass
+- [ ] Code compiles without warnings
+- [ ] Dependencies properly documented (if added)
+- [ ] Changes tested locally
+- [ ] Commit message is clear and references issue
+
+## Common CI Workflows
+
+Your changes will be validated by:
+- `server-ci.yml`: Compiles + unit/core/API tests (memory, rocksdb, hbase)
+- `licence-checker.yml`: License header validation
+- `pd-store-ci.yml`: PD and Store module tests
+- `commons-ci.yml`: Commons module tests
+- `cluster-test-ci.yml`: Distributed cluster tests
+
+## Notes
+
+- **Test Backend Selection**: Use `memory` for quick tests, `rocksdb` for realistic tests, `hbase` for distributed scenarios
+- **TinkerPop Tests**: Only run on release branches (release-*/test-*)
+- **Raft Tests**: Only run when branch name starts with `test` or `raft`
+- **Build Time**: Full build can take 5-15 minutes depending on hardware
+- **Test Time**: Test suites can take 10-30 minutes depending on backend
--- a/.serena/project.yml
+++ b/.serena/project.yml
@ -0,0 +1,84 @@
+# list of languages for which language servers are started; choose from:
+#   al               bash             clojure          cpp              csharp           csharp_omnisharp
+#   dart             elixir           elm              erlang           fortran          go
+#   haskell          java             julia            kotlin           lua              markdown
+#   nix              perl             php              python           python_jedi      r
+#   rego             ruby             ruby_solargraph  rust             scala            swift
+#   terraform        typescript       typescript_vts   zig
+# Note:
+#   - For C, use cpp
+#   - For JavaScript, use typescript
+# Special requirements:
+#   - csharp: Requires the presence of a .sln file in the project folder.
+# When using multiple languages, the first language server that supports a given file will be used for that file.
+# The first language is the default language and the respective language server will be used as a fallback.
+# Note that when using the JetBrains backend, language servers are not used and this list is correspondingly ignored.
+languages:
+- java
+
+# the encoding used by text files in the project
+# For a list of possible encodings, see https://docs.python.org/3.11/library/codecs.html#standard-encodings
+encoding: "utf-8"
+
+# whether to use the project's gitignore file to ignore files
+# Added on 2025-04-07
+ignore_all_files_in_gitignore: true
+
+# list of additional paths to ignore
+# same syntax as gitignore, so you can use * and **
+# Was previously called `ignored_dirs`, please update your config if you are using that.
+# Added (renamed) on 2025-04-07
+ignored_paths: []
+
+# whether the project is in read-only mode
+# If set to true, all editing tools will be disabled and attempts to use them will result in an error
+# Added on 2025-04-18
+read_only: false
+
+# list of tool names to exclude. We recommend not excluding any tools, see the readme for more details.
+# Below is the complete list of tools for convenience.
+# To make sure you have the latest list of tools, and to view their descriptions, 
+# execute `uv run scripts/print_tool_overview.py`.
+#
+#  * `activate_project`: Activates a project by name.
+#  * `check_onboarding_performed`: Checks whether project onboarding was already performed.
+#  * `create_text_file`: Creates/overwrites a file in the project directory.
+#  * `delete_lines`: Deletes a range of lines within a file.
+#  * `delete_memory`: Deletes a memory from Serena's project-specific memory store.
+#  * `execute_shell_command`: Executes a shell command.
+#  * `find_referencing_code_snippets`: Finds code snippets in which the symbol at the given location is referenced.
+#  * `find_referencing_symbols`: Finds symbols that reference the symbol at the given location (optionally filtered by type).
+#  * `find_symbol`: Performs a global (or local) search for symbols with/containing a given name/substring (optionally filtered by type).
+#  * `get_current_config`: Prints the current configuration of the agent, including the active and available projects, tools, contexts, and modes.
+#  * `get_symbols_overview`: Gets an overview of the top-level symbols defined in a given file.
+#  * `initial_instructions`: Gets the initial instructions for the current project.
+#     Should only be used in settings where the system prompt cannot be set,
+#     e.g. in clients you have no control over, like Claude Desktop.
+#  * `insert_after_symbol`: Inserts content after the end of the definition of a given symbol.
+#  * `insert_at_line`: Inserts content at a given line in a file.
+#  * `insert_before_symbol`: Inserts content before the beginning of the definition of a given symbol.
+#  * `list_dir`: Lists files and directories in the given directory (optionally with recursion).
+#  * `list_memories`: Lists memories in Serena's project-specific memory store.
+#  * `onboarding`: Performs onboarding (identifying the project structure and essential tasks, e.g. for testing or building).
+#  * `prepare_for_new_conversation`: Provides instructions for preparing for a new conversation (in order to continue with the necessary context).
+#  * `read_file`: Reads a file within the project directory.
+#  * `read_memory`: Reads the memory with the given name from Serena's project-specific memory store.
+#  * `remove_project`: Removes a project from the Serena configuration.
+#  * `replace_lines`: Replaces a range of lines within a file with new content.
+#  * `replace_symbol_body`: Replaces the full definition of a symbol.
+#  * `restart_language_server`: Restarts the language server, may be necessary when edits not through Serena happen.
+#  * `search_for_pattern`: Performs a search for a pattern in the project.
+#  * `summarize_changes`: Provides instructions for summarizing the changes made to the codebase.
+#  * `switch_modes`: Activates modes by providing a list of their names
+#  * `think_about_collected_information`: Thinking tool for pondering the completeness of collected information.
+#  * `think_about_task_adherence`: Thinking tool for determining whether the agent is still on track with the current task.
+#  * `think_about_whether_you_are_done`: Thinking tool for determining whether the task is truly completed.
+#  * `write_memory`: Writes a named memory (for future reference) to Serena's project-specific memory store.
+excluded_tools: []
+
+# initial prompt for the project. It will always be given to the LLM upon activating the project
+# (contrary to the memories, which are loaded on demand).
+initial_prompt: ""
+
+project_name: "server"
+included_optional_tools: []
--- a/hugegraph-server/Dockerfile
+++ b/hugegraph-server/Dockerfile
@ -34,7 +34,8 @@ COPY --from=build /pkg/hugegraph-server/apache-hugegraph-server-incubating-*/ /h
 LABEL maintainer="HugeGraph Docker Maintainers <dev@hugegraph.apache.org>"

 # TODO: use g1gc or zgc as default
-ENV JAVA_OPTS="-XX:+UnlockExperimentalVMOptions -XX:+UseContainerSupport -XX:MaxRAMPercentage=50 -XshowSettings:vm" \
+# Note: --add-exports is required for Java 11+ to access jdk.internal.reflect for auth proxy
+ENV JAVA_OPTS="-XX:+UnlockExperimentalVMOptions -XX:+UseContainerSupport -XX:MaxRAMPercentage=50 -XshowSettings:vm --add-exports=java.base/jdk.internal.reflect=ALL-UNNAMED" \
    HUGEGRAPH_HOME="hugegraph-server"

 #COPY . /hugegraph/hugegraph-server
--- a/pom.xml
+++ b/pom.xml
@ -199,6 +199,8 @@
                            <exclude>.github/**/*</exclude>
                            <exclude>.gitignore</exclude>
                            <exclude>.gitattributes</exclude>
+                            <!-- AI Tools -->
+                            <exclude>.serena/**</exclude>
                            <!-- Intellij -->
                            <exclude>**/*.iml</exclude>
                            <exclude>**/*.iws</exclude>