Skip to content

Commit 496b150

Browse files
imbajinimbajin
authored
feat: init serena memory system & add memories (#2902)
1 parent de0360b commit 496b150

14 files changed

+842
-1
lines changed

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -91,6 +91,8 @@ hs_err_pid*
9191
hugegraph-server/hugegraph-dist/docker/data/
9292

9393
# AI-IDE prompt files (We only keep AGENTS.md, other files could soft-linked it when needed)
94+
# Serena MCP memories
95+
.serena/
9496
# Claude Projects
9597
CLAUDE.md
9698
CLAUDE_*.md

‎.licenserc.yaml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,7 @@ header: # `header` section is configurations for source codes license header.
5959
- 'LICENSE'
6060
- 'NOTICE'
6161
- 'DISCLAIMER'
62+
- '.serena/**'
6263
- '**/*.versionsBackup'
6364
- '**/*.versionsBackup'
6465
- '**/*.proto'

‎.serena/.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
/cache

‎.serena/memories/architecture_and_modules.md‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
# Architecture and Module Structure
2+
3+
## Three-Tier Architecture
4+
5+
### 1. Client Layer
6+
- Gremlin/Cypher query interfaces
7+
- REST API endpoints
8+
- Multiple client language bindings
9+
10+
### 2. Server Layer (hugegraph-server)
11+
- **REST API Layer** (hugegraph-api): GraphAPI, SchemaAPI, GremlinAPI, CypherAPI, AuthAPI
12+
- **Graph Engine Layer** (hugegraph-core): Schema management, traversal optimization, task scheduling
13+
- **Backend Interface**: Abstraction over storage backends
14+
15+
### 3. Storage Layer
16+
- Pluggable backend implementations
17+
- Each backend extends `hugegraph-core` abstractions
18+
- Implements `BackendStore` interface
19+
20+
## Multi-Module Structure
21+
22+
The project consists of 7 main modules:
23+
24+
### 1. hugegraph-server (13 submodules)
25+
Core graph engine, REST APIs, and backend implementations:
26+
- `hugegraph-core` - Core graph engine and abstractions
27+
- `hugegraph-api` - REST API implementations (includes OpenCypher in `opencypher/`)
28+
- `hugegraph-dist` - Distribution packaging and scripts
29+
- `hugegraph-test` - Test suites (unit, core, API, TinkerPop)
30+
- `hugegraph-example` - Example code
31+
- Backend implementations:
32+
- `hugegraph-rocksdb` (default)
33+
- `hugegraph-hstore` (distributed)
34+
- `hugegraph-hbase`
35+
- `hugegraph-mysql`
36+
- `hugegraph-postgresql`
37+
- `hugegraph-cassandra`
38+
- `hugegraph-scylladb`
39+
- `hugegraph-palo`
40+
41+
### 2. hugegraph-pd (8 submodules)
42+
Placement Driver for distributed deployments (meta server):
43+
- `hg-pd-core` - Core PD logic
44+
- `hg-pd-service` - PD service implementation
45+
- `hg-pd-client` - Client library
46+
- `hg-pd-common` - Shared utilities
47+
- `hg-pd-grpc` - gRPC protocol definitions (auto-generated)
48+
- `hg-pd-cli` - Command line interface
49+
- `hg-pd-dist` - Distribution packaging
50+
- `hg-pd-test` - Test suite
51+
52+
### 3. hugegraph-store (9 submodules)
53+
Distributed storage backend with RocksDB and Raft:
54+
- `hg-store-core` - Core storage logic
55+
- `hg-store-node` - Storage node implementation
56+
- `hg-store-client` - Client library
57+
- `hg-store-common` - Shared utilities
58+
- `hg-store-grpc` - gRPC protocol definitions (auto-generated)
59+
- `hg-store-rocksdb` - RocksDB integration
60+
- `hg-store-cli` - Command line interface
61+
- `hg-store-dist` - Distribution packaging
62+
- `hg-store-test` - Test suite
63+
64+
### 4. hugegraph-commons
65+
Shared utilities across modules:
66+
- Locks and concurrency utilities
67+
- Configuration management
68+
- RPC framework components
69+
70+
### 5. hugegraph-struct
71+
Data structure definitions shared between modules.
72+
**Important**: Must be built before PD and Store modules.
73+
74+
### 6. install-dist
75+
Distribution packaging and release management:
76+
- License and NOTICE files
77+
- Dependency management scripts
78+
- Release documentation
79+
80+
### 7. hugegraph-cluster-test
81+
Cluster integration tests for distributed deployments
82+
83+
## Cross-Module Dependencies
84+
85+
```
86+
hugegraph-commons → (shared by all modules)
87+
hugegraph-struct → hugegraph-pd + hugegraph-store
88+
hugegraph-core → (extended by all backend implementations)
89+
```
90+
91+
## Distributed Architecture (Optional)
92+
93+
For production distributed deployments:
94+
- **hugegraph-pd**: Service discovery, partition management, metadata
95+
- **hugegraph-store**: Distributed storage with Raft (3+ nodes)
96+
- **hugegraph-server**: Multiple server instances (3+)
97+
- Communication: All use gRPC with Protocol Buffers
98+
99+
**Status**: Distributed components (PD + Store) are in BETA

‎.serena/memories/code_style_and_conventions.md‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
# Code Style and Conventions
2+
3+
## Code Style Configuration
4+
- **Import**: Use `hugegraph-style.xml` in your IDE (IntelliJ IDEA recommended)
5+
- **EditorConfig**: `.editorconfig` file defines style rules (validated in CI)
6+
- **Checkstyle**: `style/checkstyle.xml` defines additional rules
7+
8+
## Core Style Rules (from .editorconfig)
9+
10+
### General
11+
- Charset: UTF-8
12+
- End of line: LF (Unix-style)
13+
- Insert final newline: true
14+
- Max line length: 100 characters (120 for XML)
15+
- Visual guides at column 100
16+
17+
### Java Files
18+
- Indent: 4 spaces (not tabs)
19+
- Continuation indent: 8 spaces
20+
- Wrap on typing: true
21+
- Wrap long lines: true
22+
23+
### Import Organization
24+
```
25+
$*
26+
|
27+
java.**
28+
|
29+
javax.**
30+
|
31+
org.**
32+
|
33+
com.**
34+
|
35+
*
36+
```
37+
- Class count to use import on demand: 100
38+
- Names count to use import on demand: 100
39+
40+
### Formatting Rules
41+
- Line comments not at first column
42+
- Align multiline: chained methods, parameters in calls, binary operations, assignments, ternary, throws, extends, array initializers
43+
- Wrapping: normal (wrap if necessary)
44+
- Brace forcing:
45+
- if: if_multiline
46+
- do-while: always
47+
- while: if_multiline
48+
- for: if_multiline
49+
- Enum constants: split_into_lines
50+
51+
### Blank Lines
52+
- Max blank lines in declarations: 1
53+
- Max blank lines in code: 1
54+
- Blank lines between package declaration and header: 1
55+
- Blank lines before right brace: 1
56+
- Blank lines around class: 1
57+
- Blank lines after class header: 1
58+
59+
### Documentation
60+
- Add `<p>` tag on empty lines: true
61+
- Do not wrap if one line: true
62+
- Align multiline annotation parameters: true
63+
64+
### XML Files
65+
- Indent: 4 spaces
66+
- Max line length: 120
67+
- Text wrap: off
68+
- Space inside empty tag: true
69+
70+
### Maven
71+
- Compiler source/target: Java 11
72+
- Max compiler errors: 500
73+
- Compiler args: `-Xlint:unchecked`
74+
- Source encoding: UTF-8
75+
76+
## Lombok Usage
77+
- Version: 1.18.30
78+
- Scope: provided
79+
- Optional: true
80+
81+
## License Headers
82+
- All source files MUST include Apache Software License header
83+
- Validated by apache-rat-plugin and skywalking-eyes
84+
- Exclusions defined in pom.xml (line 171-221)
85+
- gRPC generated code excluded from license check
86+
87+
## Naming Conventions
88+
- Package names: lowercase, dot-separated (e.g., org.apache.hugegraph)
89+
- Class names: PascalCase
90+
- Method names: camelCase
91+
- Constants: UPPER_SNAKE_CASE
92+
- Variables: camelCase

‎.serena/memories/ecosystem_and_related_projects.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# HugeGraph Ecosystem and Related Projects
2+
3+
## Core Repository (This Project)
4+
**Repository**: apache/hugegraph (server)
5+
**Purpose**: Core graph database engine (OLTP)
6+
7+
## Related Repositories
8+
9+
### 1. hugegraph-toolchain
10+
**Repository**: https://github.com/apache/hugegraph-toolchain
11+
**Components**:
12+
- **hugegraph-loader**: Bulk data loading tool
13+
- **hugegraph-hubble**: Web-based visualization dashboard
14+
- **hugegraph-tools**: Command-line utilities
15+
- **hugegraph-client**: Java client SDK
16+
17+
### 2. hugegraph-computer
18+
**Repository**: https://github.com/apache/hugegraph-computer
19+
**Purpose**: Distributed graph computing framework (OLAP)
20+
**Features**: PageRank, Connected Components, Shortest Path, Community Detection
21+
22+
### 3. hugegraph-ai
23+
**Repository**: https://github.com/apache/incubator-hugegraph-ai
24+
**Purpose**: Graph AI, LLM, and Knowledge Graph integration
25+
**Features**: Graph-enhanced LLM, KG construction, Graph RAG, NL to Gremlin/Cypher
26+
27+
### 4. hugegraph-website
28+
**Repository**: https://github.com/apache/hugegraph-doc
29+
**Purpose**: Official documentation and website
30+
**URL**: https://hugegraph.apache.org/
31+
32+
## Integration Points
33+
34+
### Data Pipeline
35+
```
36+
Data Sources → hugegraph-loader → hugegraph-server
37+
↓
38+
┌───────────────────┼───────────────────┐
39+
↓ ↓ ↓
40+
hugegraph-hubble hugegraph-computer hugegraph-ai
41+
(Visualization) (Analytics) (AI/ML)
42+
```
43+
44+
## External Integrations
45+
46+
### Big Data Platforms
47+
- Apache Flink, Apache Spark, HDFS
48+
49+
### Storage Backends
50+
- RocksDB (default), HBase, Cassandra, ScyllaDB, MySQL, PostgreSQL
51+
52+
### Query Languages
53+
- Gremlin (Apache TinkerPop), Cypher (OpenCypher), REST API
54+
55+
## Version Compatibility
56+
- Server: 1.7.0
57+
- TinkerPop: 3.5.1
58+
- Java: 11+ required
59+
60+
## Use Cases
61+
- Social networks, Fraud detection, Recommendation systems
62+
- Knowledge graphs, Network analysis, Supply chain management
63+
- IT operations, Bioinformatics

‎.serena/memories/implementation_patterns_and_guidelines.md‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
# Implementation Patterns and Guidelines
2+
3+
## Backend Development
4+
5+
### Backend Architecture Pattern
6+
- All backends extend abstractions from `hugegraph-server/hugegraph-core`
7+
- Implement the `BackendStore` interface
8+
- Each backend is a separate Maven module under `hugegraph-server/`
9+
- Backend selection configured in `hugegraph.properties` via `backend` property
10+
11+
### Available Backends
12+
- **RocksDB** (default, embedded): `hugegraph-rocksdb`
13+
- **HStore** (distributed, production): `hugegraph-hstore`
14+
- **Legacy** (≤1.5.0): MySQL, PostgreSQL, Cassandra, ScyllaDB, HBase, Palo
15+
16+
### Backend Testing Profiles
17+
- `memory`: In-memory backend for fast unit tests
18+
- `rocksdb`: RocksDB for realistic local tests
19+
- `hbase`: HBase for distributed scenarios
20+
- `hstore`: HStore for production-like distributed tests
21+
22+
## gRPC Protocol Development
23+
24+
### Protocol Buffer Definitions
25+
- PD protos: `hugegraph-pd/hg-pd-grpc/src/main/proto/`
26+
- Store protos: `hugegraph-store/hg-store-grpc/src/main/proto/`
27+
28+
### Code Generation
29+
When modifying `.proto` files:
30+
1. Run `mvn clean compile` to regenerate gRPC stubs
31+
2. Generated Java code goes to `*/grpc/` packages
32+
3. Output location: `target/generated-sources/protobuf/`
33+
4. Generated files excluded from Apache RAT checks
34+
5. All inter-service communication uses gRPC
35+
36+
## Authentication System
37+
38+
### Default State
39+
- Authentication **disabled by default**
40+
- Enable via `bin/enable-auth.sh` or configuration
41+
- **Required for production deployments**
42+
43+
### Implementation Location
44+
`hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/auth/`
45+
46+
### Multi-Level Security Model
47+
- Users, Groups, Projects, Targets, Access control
48+
49+
## TinkerPop Integration
50+
51+
### Compliance
52+
- Full Apache TinkerPop 3 implementation
53+
- Custom optimization strategies
54+
- Supports both Gremlin and OpenCypher query languages
55+
56+
### Query Language Support
57+
- **Gremlin**: Native via TinkerPop integration
58+
- **OpenCypher**: Implementation in `hugegraph-api/opencypher/`
59+
60+
## Testing Patterns
61+
62+
### Test Suite Organization
63+
- **UnitTestSuite**: Pure unit tests, no external dependencies
64+
- **CoreTestSuite**: Core functionality tests with backend
65+
- **ApiTestSuite**: REST API integration tests
66+
- **StructureStandardTest**: TinkerPop structure compliance
67+
- **ProcessStandardTest**: TinkerPop process compliance
68+
69+
### Backend Selection in Tests
70+
Use Maven profiles:
71+
```bash
72+
-P core-test,memory # Fast in-memory
73+
-P core-test,rocksdb # Persistent local
74+
-P api-test,rocksdb # API with persistent backend
75+
```
76+
77+
## Distribution and Packaging
78+
79+
### Creating Distribution
80+
```bash
81+
mvn clean package -DskipTests
82+
```
83+
Output: `install-dist/target/hugegraph-<version>.tar.gz`
84+
85+
## Code Organization
86+
87+
### Package Structure
88+
```
89+
org.apache.hugegraph
90+
├── backend/ # Backend implementations
91+
├── api/ # REST API endpoints
92+
├── core/ # Core graph engine
93+
├── schema/ # Schema definitions
94+
├── traversal/ # Traversal and query processing
95+
├── task/ # Background tasks
96+
├── auth/ # Authentication/authorization
97+
└── util/ # Utilities
98+
```
99+
100+
### Module Dependencies
101+
- Commons is shared by all modules
102+
- Struct must be built before PD and Store
103+
- Backend modules depend on core
104+
- Test module depends on all server modules

0 commit comments

Comments
 (0)